run
Execute a single Claude agent in a Docker container to complete a task prompt. Configure resources, tools, model, and execution limits for isolated and customizable agent execution.
Instructions
Run a single Claude agent in a Docker container. Returns the agent's text output and metadata.
Args: prompt: The task prompt for the agent. sandbox: Named sandbox spec (from ~/.claude/sandboxes/) or inline JSON. Overrides below are merged on top. network: Whether the container has network access (default: true — needed for API calls). tools: Comma-separated list of allowed Claude tools (default: Read,Write,Glob,Grep,Bash). mounts: JSON array of mount specs: [{"host_path": "...", "container_path": "...", "readonly": true}]. model: Claude model to use (default: sonnet). Options: haiku, sonnet, opus. timeout: Max execution time in seconds (default: 120). system_prompt: System prompt injected via --system-prompt (role, persona, instructions). claude_md: Project instructions written to workspace CLAUDE.md. output_schema: JSON schema string for structured output (--json-schema). mcps: JSON array of MCP server names to attach: ["database-mcp", "whatsapp"]. effort: Effort level: low, medium, high, max. max_budget: Explicit USD budget cap. env_vars: JSON object of environment variables: {"KEY": "value"}. input_files: JSON object of files to inject: {"/path": "content"}. memory: Docker memory limit (e.g. "2g"). cpus: Docker CPU limit (e.g. 2.0). gpu: Pass --gpus all to Docker for GPU access (default: false). Acquires the "gpu" resource pool (capacity 1). resources: JSON array of named resource pools to acquire before execution (e.g. '["gpu", "database"]'). Agents wait for all resources. Configure capacity via SWARM_RESOURCE_= env vars. input_type: Natural language type describing what the agent receives (e.g. "research notes", "[code-review]"). output_type: Natural language type describing what the agent must produce (e.g. "[mcp-server] with [test-suite]").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| sandbox | No | ||
| network | No | ||
| tools | No | Read,Write,Glob,Grep,Bash | |
| mounts | No | [] | |
| model | No | sonnet | |
| timeout | No | ||
| system_prompt | No | ||
| claude_md | No | ||
| output_schema | No | ||
| mcps | No | ||
| effort | No | ||
| max_budget | No | ||
| env_vars | No | ||
| input_files | No | ||
| memory | No | ||
| cpus | No | ||
| gpu | No | ||
| resources | No | ||
| input_type | No | ||
| output_type | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |