Outpost

Coding agents. Isolated workspaces. Workflows in TypeScript.

Quickstart · Documentation · API reference · Français

Outpost is a TypeScript library and CLI for running coding agents in sandboxes and composing their work. Give an agent a task, choose its execution environment, and collect its answer, commits and usage. Start with one request; add parallel tasks, verification loops and human decisions as your workflow grows.

Why Outpost?

• Choose your agent and sandbox independently. Run Claude Code, Codex, Antigravity, GitHub Copilot CLI or Kimi Code with Docker, Podman, Vercel or Daytona.
• Keep Git work explicit. Give tasks their own worktrees, retain branches for review, or opt into local integration. Compose work across repositories with declared dependencies.
• Write workflows as code. Connect typed tasks, validate structured responses, enforce budgets and pause for human input or approval.
• Continue work across runs. Capture supported agent conversations, resume checkpointed workflows and recover interrupted work with explicit replay controls.
• Build your own agent loop. Use the built-in harness with OpenAI or Anthropic model providers, sandbox tools and bounded subagents.

Quickstart

You need Node.js 24+, Git, a repository with at least one commit, and Docker running. This example uses Codex with account authentication: prepare its host login using the Codex guide before running a task. Authentication covers other agents and API-key billing.

Install the package, then build the agent image in a dedicated directory:

npm install @elie-laloum/outpost
npm pkg set type=module
npx outpost init --yes --directory .outpost-image --image outpost:dev

The first build downloads the agent CLIs. The image directory also receives example workflow files; write your own script as shown below. See agent images to add project tools or use Podman.

Write a TypeScript script

Use an ESM directory ("type": "module" in package.json); a CommonJS repository can keep the scripts in a separate directory with its own manifest. Save this as task.ts, replace the repository path, and run it with node task.ts. It keeps the agent’s changes on a named branch for review:

import {
  createAgent,
  createCodexHarness,
  createReporter,
  dispatch,
} from "@elie-laloum/outpost";
import { createDockerSandboxProvider } from "@elie-laloum/outpost/providers/docker";

const result = await dispatch({
  repository: "/absolute/path/to/repository",
  agent: createAgent({
    harness: createCodexHarness({ authentication: "account" }),
  }),
  sandboxProvider: createDockerSandboxProvider({ image: "outpost:dev" }),
  observe: createReporter(),
  branch: { mode: "named", name: "outpost/fix-tests" },
  brief: {
    text: "Fix the failing tests, run them to verify and commit the change.",
  },
});

// Example output:
// [outpost · pass 1] running · codex
// Fixed the failing tests and committed the change.
// [outpost · pass 1] finished · 12.00s · status 0 · input 1200 · cache read 0 · cache write 0 · output 320

dispatch() closes the sandbox it allocates; the named branch remains for review. Use a fresh branch name for each independent task. The agent’s answer is not an enforced test result: add explicit verification when checks must gate integration.

Choose your building blocks

The Guide explains behavior with focused examples. The Reference documents exact contracts. Both are available in English and French.

Boundaries worth knowing

Account login and API-key authentication are explicit choices with different billing. Outpost never reads a system keychain. Credentials are made available to the chosen agent in its execution environment.

Conversation support varies: Claude Code, Codex and Kimi support capture, resume and fork; Copilot supports capture and resume; Antigravity resumes only in its existing sandbox.

Docker and Podman mount the selected workspace and Git metadata by default. These mounts are not an adversarial security boundary. Cloud providers receive repository data and declared credentials; explicit local execution runs on the host without isolation. Read SECURITY.md before choosing an environment for untrusted code.

Speculation remains experimental. See the speculation guide for validation limits and the changelog for version history.

Development and contributions

Bug reports, reproducible cases and focused contributions are welcome through GitHub issues. Read AGENTS.md for architecture, conventions and the checks required for your change.

bun install --frozen-lockfile
bun run check
bun run coverage
bun run test:package

CI checks Windows, macOS and Linux, plus real Docker/Podman execution and Redis queue behavior. The coverage gate requires at least 80% lines, branches and functions; the badge shows that configured minimum, not a measured coverage percentage. Coverage reports are uploaded as CI artifacts. Routine tests do not require paid model calls.

GitLab is the canonical repository. GitHub is the public mirror and runs CI, package releases and documentation deployment. The documentation site deploys after eligible stable releases.

Created by Elie Laloum. Released under the MIT license.