Give the Entity useful reach

Tools let the Entity act on information and its environment. Their registry describes available interfaces; credentials, dependencies, execution policy, and surface connections determine whether a particular call can work.

Discover the running registry

Ask the Entity to use search_tools to find a capability and describe_tool to inspect its exact schema. Telegram /tools also exposes registered tools. Do not depend on one fixed tool count. Configuration and MCP connections change the registry, and a truncated discovery result may return only part of it.

Area	Examples
Research	`search_web`, `fetch_url`
Files and execution	`read_file`, `write_file`, `run_command`, Python and JavaScript execution
Persistent work	Knowledge, journals, projects, reminders, routines
Communication	Configured messaging and voice tools
Spatial	Movement, gestures, panels, programmable creations, Blender projects, environment, and capture
Extensions	Tools discovered from configured MCP subprocesses

The spatial reference documents every shipped spatial tool and its parameters. ar_world composes many creation operations through one interface. Distinct consecutive requests are allowed; three identical consecutive requests trigger the retry guard. Inspect, act, and verify instead of continuously polling. Blender previews and local programs keep updating without model polling.

Send a long-running coding goal

Use code_task_session for coding work that should continue independently of the chat connection. Give it a self-contained objective, repository path, success criteria, and any constraints on publishing or deployment. It returns a task ID immediately.

{
  "objective": "In workspace repo/, fix the parser to accept empty input. Preserve unrelated changes and do not publish.",
  "success_criteria": "Empty input returns an empty result; existing parser tests pass; add an empty-input regression test.",
  "steps_per_phase": 24,
  "max_phases": 0,
  "max_runtime_seconds": 21600
}

The worker loops through implementation phases with fresh context and saved handoffs. A completion claim needs successful tool evidence, followed by a fresh verification phase that inspects the workspace against the success criteria. end_turn only ends a phase. Exhausting a budget leaves the goal paused and incomplete.

Tool	Purpose
`code_task_status(task_id)`	Read status, recent progress, next steps, and tool evidence. Omit the ID to list goals.
`code_task_resume(task_id, instructions, additional_seconds)`	Continue saved work, add guidance, and extend the runtime allowance.
`code_task_cancel(task_id)`	Stop scheduling work. An executing tool finishes before cancellation completes.

max_phases: 0 removes the phase-count limit; the default runtime allowance is six hours. Repeated lack of new tool evidence pauses a goal after three phases. The same external blocker must recur for three consecutive phases before the goal becomes blocked. Repeated execution errors produce a resumable failed state. These states never imply completion. One coding goal runs at a time per Entity, with additional goals queued. Each goal uses its own model context and a coding tool subset; normal chat remains available. Telegram and Discord receive progress sent with say and a final status at the original channel. Progress is also saved under code_tasks/ in the execution workspace. Browser disconnects do not cancel the goal. The authoritative JSON records live in .code_tasks/ beside the Entity journal and use atomic replacement. Keep this directory on persistent storage and run one worker per Entity data directory. Active goals recover on daemon or bridge startup. Restart recovery includes the last pending tool call so the worker can inspect its effects before retrying. A process killed during a command may leave an uncertain outcome; recovery does not promise exactly-once command execution. Paused, blocked, failed, and cancelled goals require explicit resume. Inference pause also pauses coding goals. The authenticated Entity bridge exposes GET /code-tasks, GET /code-tasks/{task_id}, and POST /code-tasks/{task_id}/resume or /cancel. These controls do not depend on the original WebSocket. Resume accepts instructions and additional_seconds in its JSON body. The tools and bridge use the same saved state.

Configure capabilities

Harness tool settings live in configs/default.yaml. A top-level tools block in Entity YAML can override them:

tools:
  shell:
    enabled: false
  browser:
    enabled: false
  imagegen:
    enabled: false

Disabling one category does not disable all ways to perform related work. For example, shell and code execution are separate capabilities. Review the complete registry and execution policy for the access you intend to grant.

Choose the execution host

Shell, code, and filesystem tools use the execution client. A configured RPC endpoint takes precedence; local fallback is gated by settings and the deployment environment. For a dedicated local development workspace, an explicit configuration is:

tools:
  shell:
    enabled: true
  execution:
    allow_local: true
    workspace_dir: "./workspace"

Create the directory before use and run ngram from the intended application checkout. This grants local execution; the workspace setting and shell denylist are not a substitute for process isolation. See deployment security.

Add an MCP tool

The v1 MCP hub launches stdio servers. A URL-only HTTP MCP configuration is not handled directly by this hub. Create tools/hello_mcp.py in your application checkout:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello")

@mcp.tool()
def greet(name: str) -> str:
    """Return a greeting for a named person."""
    return f"Hello, {name}."

if __name__ == "__main__":
    mcp.run(transport="stdio")

Add this to the Entity declaration:

mcp_servers:
  hello:
    command: uv
    args: ["run", "python", "tools/hello_mcp.py"]

Start the Entity from the application root. The hub discovers the server tool and registers it as mcp_hello_greet. Ask the Entity to describe that tool, then call it with a name. The example needs no service credential. MCP subprocesses inherit a runtime environment and can have their own access. Keep real credentials in the private environment instead of copying them into committed YAML.

Optional dependencies

Install only the extras needed for your configured capabilities. From the source checkout:

uv sync --extra dev --extra voice --extra pdf

The application also defines browser, imagegen, youtube, and full extras. An installed package does not configure its external backend. Verify the tool result before claiming a capability is operational.

Getting started

Entities

Surfaces

Explore

Give the Entity useful reach

Discover the running registry

Send a long-running coding goal

Configure capabilities

Choose the execution host

Add an MCP tool

Optional dependencies

​Discover the running registry

​Send a long-running coding goal

​Configure capabilities

​Choose the execution host

​Add an MCP tool

​Optional dependencies

Discover the running registry

Send a long-running coding goal

Configure capabilities

Choose the execution host

Add an MCP tool

Optional dependencies