Documentation Index
Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
Use this file to discover all available pages before exploring further.
CAMEL-AI is a multi-agent framework with a large ecosystem of toolkits. Mirage ships two of those toolkits, terminal and file, backed by a Workspace instead of the host. The agent’s shell, file reads/writes, and search all run inside Mirage; mount RAM, S3, GDrive, Slack, etc. and the agent uses them through the same camel API.
Install
uv add 'mirage-ai[camel]'
camel-ai>=0.2.40,<0.3 and markitdown>=0.1.5. Note: mirage-ai[camel] is mutually exclusive with [openai], [openhands], and [pydantic-ai], camel pins pydantic<=2.12.0 while the other agent SDKs require >=2.12.2. Pick one stack per environment.
Usage
import asyncio
from camel.agents import ChatAgent
from camel.messages import BaseMessage
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType
from mirage import MountMode, Workspace
from mirage.agents.camel import MirageFileToolkit, MirageTerminalToolkit
from mirage.resource.ram import RAMResource
ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
terminal = MirageTerminalToolkit(ws)
files = MirageFileToolkit(ws)
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI,
model_type=ModelType.GPT_5_MINI,
)
agent = ChatAgent(
system_message=BaseMessage.make_assistant_message(
role_name="Mirage Camel Agent",
content="You operate over a Mirage virtual filesystem mounted at /.",
),
model=model,
tools=[*terminal.get_tools(), *files.get_tools()],
)
response = await asyncio.to_thread(
agent.step,
"Write /data/numbers.csv with 3 rows, then read it back.",
)
print(response.msgs[-1].content)
terminal.close()
files.close()
TerminalToolkit. Same 6 functions, all routed through Workspace.execute():
| Method | Mirage translation |
|---|
shell_exec(id, cmd, block=True) | await ws.execute(cmd) |
shell_exec(id, cmd, block=False) | await ws.execute(f"{cmd} &"), uses Mirage’s JobTable |
shell_view(id) | jobs (status) or wait %N (final stdout) |
shell_kill_process(id) | kill %N |
shell_write_content_to_file | cat > path with stdin= |
shell_write_to_process | Returns a clear error, Mirage’s shell is non-interactive |
FileToolkit, inherits all 7 public methods and every format writer (PDF, DOCX, JSON, CSV, HTML, ipynb, plain text). Path resolution and IO are overridden to route through Mirage; format writers operate on a tempfile and the result is pushed via Workspace.execute(f"cat > {path}", stdin=...).
| Method | Behavior |
|---|
write_to_file(title, content, filename) | Format writer runs in tempdir → bytes pushed to Mirage path |
read_file(file_paths) | Bytes pulled from Mirage → tempfile → camel’s MarkItDown converter |
edit_file(file_path, old, new) | In-place text replacement via Mirage |
search_files(file_name, path) | find <path> -name <file_name> |
glob_files(pattern, path) | Same as search_files |
grep_files(pattern, path) | grep -rn <pattern> <path> |
Exports
| Symbol | Purpose |
|---|
MirageTerminalToolkit | Camel BaseToolkit exposing the 6 shell tools, backed by Workspace.execute. |
MirageFileToolkit | Subclass of camel’s FileToolkit routing path/IO through Mirage. |
Examples
Home
Python
TS
