Core concepts

A real example:

A good goal is:

• Specific — names the inputs to use and what to do with them.
• Output-aware — names the artifact ID and format.
• Actionable — imperative verbs ("Research", "Write", "Analyze").
• Structured — a 10-line goal with numbered sections almost always beats a 2-line one.

AppArtifactDef — what each stage produces

Seven supported formats:

All artifacts are stored in S3 (or R2 if you self-host) under app_artifact.s3_key, with MIME type and byte size recorded. Stored for the lifetime of the App; deleted App archives are recoverable for 30 days.

Resources — Skills and Connects the App needs

Skills are capability modules the agent can call (web search, PDF extraction, image generation) — see Skills. Connects are the OAuth bridges the App needs. Aitroop tracks Connects in a two-level taxonomy:

• type: "specific" — pin a single provider by its connect_definition.id (e.g. github, hubspot, gmail). Use this when only one integration will do.
• type: "category" — accept any provider in a connect_category (e.g. email, storage, crm). The App is satisfied if the user has authorized at least one provider in that category. Use this when the App is provider-agnostic ("any email", "any CRM").

The legacy form "connects": ["hubspot", "github"] still works — each string is treated as { type: "specific", id: «string», is_required: true } when the App runs. The App Builder writes the rich form for new apps.

Resources can be declared App-wide (as above) or per-stage (under stage.skills / stage.connects). Per-stage scoping is the way to make a multi-stage App safer — give stage 1 only web-search, stage 2 only the CRM Connect, and so on. See Connects for the full provider catalog and the satisfaction model.

Executions — when an App actually runs

An Execution is one trip through an App's stages. It's the thing with a status, a stage log, a duration, and a final set of artifacts.

Every stage in the execution gets its own app_stage_log row with status, duration, the session ID (so you can open it as a chat), the expanded goal, and any error.

The status enums are not the same at the two levels:

Stage logs go to waiting while a human stage holds the run; the parent execution stays in running. They also go to skipped when an execution is resumed with start_from_stage_index > 0 — the earlier stages aren't re-run. See Executions for the full lifecycle, debug flows, and SSE streaming.

Sandbox — where the agent does its work

Every chat and every App stage runs inside a sandbox: an isolated runtime with its own filesystem, its own processes, and outbound network. The agent can pip install, run shell commands, write files, fetch URLs — and when the run ends, the sandbox is destroyed.

Three backend providers under one ISandbox interface, plus a router that picks between them:

• host — runs directly on the Aitroop server process. Self-hosted dev installs only; secrets like DATABASE_URL, JWT_SECRET, E2B_API_KEY, and S3 credentials are stripped from the child environment.
• e2b — Firecracker microVMs from E2B. Default for hosted Aitroop.
• daytona — managed dev containers from Daytona. For heavy / longer-running stages.
• router — selector that dispatches to one of the three above per user (used to route privileged users to host).

Every sandbox exposes the same path layout, regardless of provider, rooted at the sandbox user's home directory:

All stages in a single execution share the same sandbox, so stage 2 can read what stage 1 wrote. Different executions get different sandboxes — nothing leaks across runs. The constants you'll hit in practice: SANDBOX_IDLE_TIMEOUT_MS = 5 min, SANDBOX_KEEPALIVE_INTERVAL_MS = 30 s, and an upper-bound AGENT_RUN_TIMEOUT_MS = 7 days. See Sandbox for the full operational model.

Multi-stage Apps

When a workflow naturally has steps that feed each other, define multiple stages. Stages run sequentially. Each stage sees the prior stages' artifacts in two places — neither of which uses goal templating:

1. The shared sandbox filesystem. All stages in one execution run inside the same sandbox (Sandbox). Files Stage 1 writes are still there for Stage 2 to read.
2. An auto-injected ## Previous Stage Outputs section in the system prompt. Before stage N runs, the executor loads every artifact produced by stages 0..N-1, renders each as ### {{title}}\n{{content}}, and prepends the block to the system prompt. The agent reads them as plain context — no manual reference needed in the goal.

Notice the human stage between two agent stages — that's the human-in-the-loop pattern. Execution pauses there, the platform creates a row in app_human_gate with status pending, and the stage log transitions to waiting. The next stage only runs after the gate is set to approved (or stays paused on rejected).

Sessions and the message queue

Every conversation with the agent — whether it's a free-form chat, an App stage, or a tick of a scheduled task — happens inside a session. A session is a stable container with its own Claude conversation ID, its own ordered message log, and its own status-tracked queue. Three flavours are persisted in app_session.session_type:

Inside each session, every user turn is a row in app_message. Rows aren't "fire-and-forget" — they go through a small state machine because the agent worker pool can be multi-instance and a single session must serialize its dispatches:

The columns that matter on app_message:

• position — integer per session, monotonically increasing. Determines order within equal-priority rows. The DAO assigns this atomically when the row is inserted.
• priority — a 64-bit sort key. Higher priority dispatches first; default is wall-clock time so two messages without explicit priority run in arrival order.
• attempts — increments on each dispatch try. After 5 failures the row goes to failed and the user-visible message shows the error.
• dispatched_at — set when a worker claims the row; combined with a 15-minute staleness threshold drives the recovery poller.
• mode — free-form tag for what kind of message this is (used to route formatting in the UI).
• last_error — last failure reason, kept across retries.

Workers claim work with SELECT … FOR UPDATE SKIP LOCKED ordered by priority DESC, position ASC, so two instances will never pick the same row. A partial unique index — uq_app_message_inflight over session_id WHERE status = 'dispatching' AND role = 'user' — enforces "at most one in-flight user message per session" at the database level. If a row stays in dispatching for more than 900 s (worker crash, node lost), a recovery poller resets it to pending so another worker can pick it up.

How dispatch actually moves

The mechanism is two layers: an in-process QueueController and a Postgres NOTIFY channel called queue_dispatch. When a new message is queued, the writing instance broadcasts a queue_updated event locally and emits pg_notify('queue_dispatch', '{sessionId}|{originInstanceId}'). Other instances listening on the same channel ignore their own echoes and pick up the work — so dispatch is event-driven across the cluster, with a 60 s poll as a safety net for missed notifications.

The shared-session flag

Normally each App stage gets its own session. When RunAppRequest.shared_session is true, the executor creates one session for the whole execution and reuses its session_id across every agent stage. The visible difference: Debug in chat on the execution opens a single chat that contains every stage's messages in order, instead of one chat per stage. Useful when you want to read the run as a narrative; rarely needed otherwise.

The ask_user pattern

Agents occasionally need to ask the user something mid-run (an ambiguity, a missing piece of input). Emitting an ask_user tool call pauses the agent's turn, surfaces the question in the chat UI, and waits for a reply. The platform routes the reply back as the tool result on the next tick — so the agent's "I asked, here's the answer" is a normal conversational step from the model's point of view. Distinct from human stages (which gate the whole pipeline at the execution level); ask_user is purely intra-session.

The agent runner protocol

Every agent stage and every chat turn ultimately runs through a Go binary called run-agent. The server hands the binary a JSON config and reads its stdout line-by-line. Each line is one event — a stable JSONL protocol you'll see referenced in logs, in SSE payloads, and in the chat UI's reasoning trace.

Forwarded events

These are emitted to the UI as they arrive. Field names are camelCase on the wire to JS; the runner's snake_case is auto-converted (tool_id → toolId, is_error → isError, etc.).

Internal events (never forwarded)

Three events with __runner_*__ names are consumed by the server only — they're bookkeeping, not user-visible state:

Error classification

Not every runner failure is the same. The server classifies the captured error message into one of five buckets — the bucket determines the recovery strategy:

What's in the run config

The server builds a RunAgentConfig per turn and writes it to ~/.aitroop/run-agent-config.json inside the sandbox before invoking the binary. The salient fields:

• prompt — the actual user message (or the stage's expanded goal).
• options.model — Claude model ID; defaults to claude-sonnet-4-6 if the stage didn't pin one.
• options.resume — when present, resume an existing Claude conversation. The server pulls this from the session's agent_session_id.
• options.allowedTools — the curated tool set the runner exposes to the model (typically 8 names: Read, Edit, Bash, Glob, Grep, Write, Task, plus the Aitroop MCP set).
• options.permissionMode — fixed to 'bypassPermissions'; the platform enforces permissions at the sandbox boundary, not interactively.
• options.mcpServers — the Aitroop in-house MCP server plus any extras the App / stage requested.
• options.env — anything in process.env prefixed with SANDBOX_ENV_ is forwarded with the prefix stripped, plus AT_USER_TOKEN (the user's JWT) is injected so authenticated server calls work from inside the sandbox.
• options.oauthToken / proxy mode — either an Anthropic OAuth token or, when a proxy is configured, an ANTHROPIC_BASE_URL pointing at the proxy with the user's JWT used as bearer. The platform snapshots this once per call so all retries within a turn use the same credentials.

How Apps actually get created

You don't write the App JSON by hand. The agent does it. The flow:

1. You tell the agent in chat: "Create an app that…"
2. The agent activates the aitroop-app-create Skill (the App Builder).
3. The App Builder asks 1–5 clarifying questions if needed.
4. It designs the full AppDef (inputs, stages, artifacts, resources).
5. It validates the design — every ID unique, every {{ref}} resolves, goals are specific.
6. It calls POST /api/apps to save.
7. It reports the App ID and offers to refine.

To edit an existing App, you say something like "Update my Company Brief app to also include hiring data" and the App Builder fetches the current version, modifies it, and calls PUT /api/apps/{id}.

Common mistakes to avoid

• Vague goals — "Do research" is too vague. Specify sources, depth, output format.
• Missing artifacts — an App with no artifact_defs produces no visible output.
• Too many required inputs — users abandon Apps with long forms. Default everything you can.
• Undersized timeout — heavy research stages need 5–10 min. Bump timeout_ms to 600000.
• Wrong input type — use textarea for long text, text for short identifiers, select when there are 3–6 fixed options.
• Over-decomposing — splitting a one-thought task into 4 stages. Use multi-stage only when the work naturally has separable steps.

Quick glossary