robodev

DocsSign in

Guides

Agents

Reusable file sessions and ctx.agent.start — a CLI agent in Docker, not the Build chat.

Getting startedOffline dev with robodev devConnect a frontendStartersDatabaseDomainsFile-based APIsAuthEmailPDFOrganizationsStorageSecretsPushJobsSocketsLLMAgentsDeployLocal developmentCLI reference

Every defineApi, defineJob, and defineSocket handler receives an injected agent client. Tenant agents are reusable file workspaces per project. They are not the dashboard Build chat, not Cursor, and they never open a browser for CLI login. API keys come from the project AI page (bring your own key) — the same encrypted project_ai_keys store as ctx.llm.

createSession picks a provider (default: first configured in grok → gemini → openai → anthropic). Missing that key throws llm_not_configured. A project may keep up to five idle sessions until you destroy them or delete the project. Files in a session persist across start calls until destroy.

agent.start enqueues a Docker run and returns immediately with { runId, sessionId }. It does not wait for the CLI. API handlers must return in well under 30s. Follow progress with agent.events(runId) or agent.subscribe(runId, cb). subscribe is in-process only. One queued or running tenant run per project (independent of Build — both may run at the same time). A second start while busy throws agent_busy (HTTP 409).

ctx.agent.start

robodev/api/agent.ts

import { defineApi, z } from "@robodev-ai/sdk";
export const post = defineApi({
  body: z.object({ prompt: z.string().min(1) }),
  handler: async ({ agent, body }) => {
    const session = await agent.createSession({ provider: "grok" });
    const started = await agent.start({
      sessionId: session.id,
      prompt: body.prompt,
      tools: { terminal: true, webFetch: true },
    });
    return started;
  },
});

File workspace

  • Each session is a tmp workspace hydrated from stored files, then synced back when the run finishes.
  • destroy drops files and cannot resume. If a run is queued or running on that session, it is failed and the container is killed.
  • v1 tools flags are optional (terminal and webFetch, default both true). There are no custom JS tools. If a CLI still has built-in network or shell tools, v1 may not fully disable them.
  • The runner image is robodev-tenant-agent:local (TENANT_AGENT_RUNNER_IMAGE). It is a different Docker image from Build. It does not mount grok-home and does not inherit host XAI_API_KEY / GEMINI_API_KEY.