~/sursakit

// docs

Codex agent

Codex is Sursakit's AI agent. It runs inside an isolated runner container, talks to your workspace through the same APIs you use, and ships work as pull requests scoped to a session.

How Codex is wired

  • Runner image — a separate Docker image that boots a minimal Linux environment for the agent to work in. It includes common tooling (jj, git, language runtimes) and the platform's system skill.
  • Device authentication — Codex authenticates via a short-lived device flow scoped to your account, so the agent can only touch resources you've granted it.
  • MCP control plane — the agent reaches your workspace through a Model Context Protocol server hosted by Sursakit. Capabilities are scoped through a token-signed bearer credential, which means Codex can never reach beyond what's been authorised.
  • Session-scoped — every Codex run is bound to a session. The agent commits to that session and opens its pull requests against it.

What Codex can do

  • Read and edit files across every service in the workspace.
  • Run commands in real PTYs against running service containers — the same terminals you'd open by hand.
  • Use the version-control surface — log, diff, commit, generate commit messages, push.
  • Open and review pull requests against GitHub, GitLab, or Bitbucket.
  • Use skills — reusable capabilities you've defined or that Sursakit ships as system skills.

What Codex can't do

  • Reach outside the workspace's resources. The MCP control plane is the only tool surface; it's bound to the session's permissions.
  • Use a skill that hasn't been activated for the workspace — workspace owners explicitly opt in.
  • Bypass code review. Work always lands as a commit + pull request you (or a teammate) approve.

Invoking Codex

You can hand work to Codex from three places:

  1. Chat panel — describe a task in the right rail of the workbench.
  2. Tasks — assign a task to Codex by mentioning the agent as the assignee.
  3. Automations — trigger Codex on a schedule, on a webhook event, or manually.

Auditing Codex runs

Every run is a chat thread you can open and replay. Tool calls, terminal output, file edits, commits, and pull request links are all attached to the thread.

Related