gateship

Gateship is a local software-delivery runtime for coding agents. An operator defines a task, and Gateship gives it an isolated Git worktree, runs the selected local Claude Code or Codex client, verifies the acceptance commands written into the task, asks an independent read-only reviewer to inspect the change, and ships the result through a squash-merged pull request. The product is web-first and local-first: Bun serves the interface on 127.0.0.1, SQLite stores run state and activity, and no terminal keystrokes or tmux session sit on the execution path. Requirements and credential handling. Docker Desktop on Windows and macOS, or Docker Engine with the Compose plugin on Linux, is the recommended installation when host portability is required, and the image includes the provider and GitHub CLIs. Native macOS and Linux installs need Claude Code and/or Codex CLI with a subscription login, plus the GitHub CLI authenticated through gh auth login --web and gh auth setup-git. Bun 1.2.3 or newer is required only when running from source, and Git must be able to create branches and worktrees in the target repository. Gateship executes the operator's signed-in claude or codex binary, passes agent children an allowlisted environment, never reads provider credential files and does not use an Agent SDK; GitHub shipping uses the credential store owned by gh rather than an ambient personal access token. Install and update. The installer script places gateship and the shorter gship alias in ~/.local/bin by default, with GATESHIP_INSTALL_DIR to override the destination; re-running it replaces an existing installation in place, and GATESHIP_VERSION can pin a specific release. Source builds use bun install --frozen-lockfile followed by bun run build:release, and Bun can also run the entry point directly for development. Native installations may opt in, off by default, to update checks under Settings; the running process checks official releases at most once a day, verifies the release tag commit, the current platform asset, SHA256SUMS.txt and the candidate's own version output, then hands off only while no non-terminal run or active diagnostic exists. A candidate that does not return the exact release version and commit is stopped, and the previous binary is restored, restarted and verified. Automatic apply is unavailable in containers and source checkouts; those report why. Quick start. Running gship from a GitHub clone starts the local control surface and prints http://127.0.0.1:7777, and gship --port 8080 selects another port. On first load the web interface checks only local Git metadata, the origin URL and the local origin/main ref, and never fetches or creates a repository implicitly. If the directory is empty or incomplete, operational surfaces show the exact recovery command while settings remain available for agent subscription setup. The operator name and IANA timezone are optional and stored only after an explicit save. A running process cannot switch its own working directory, so a changed project path requires restarting Gateship from the intended clone. Agent CLI. Shell-capable agents can use the running service through a versioned, machine-readable interface instead of starting another runtime or editing the .gship directory directly: gship agent guide, gship agent operations, gship agent call status.get, and calls such as issues.get with a JSON input. Every agent command emits one JSON object without ANSI or progress output, and a URL flag points at a service running on a different port. The browser workflow lets an operator describe and refine work with an external agent that invokes typed Gateship commands, maintain a durable project brief as handoff between sessions, then authorize the task explicitly. Decisions interrupt the work and wait for attention, while progress, public agent text, tool names, verification and review are followed over SSE; local browser notifications can reach the operator outside the tab. Claude and Codex can be switched without losing durable run state, and explicit controls act as a deterministic fallback. An optional advisory React diagnostic runs against an isolated exact-SHA checkout, manually or on a daily or weekly schedule while the project is idle; a finding can be dismissed or promoted into an unapproved task. Diagnostics stay outside the delivery gate, never auto-fix or approve work, and no diagnostic score can block shipping. A benchmark panel keeps outcomes, human attention, correction rounds, provider holds, wall time, cost and provider or model facts visible as separate items, with no evaluator model or synthetic score. Runtime flow. An operator task goes to an external conversational agent, then a typed Gateship command, then a backlog record on remote main. Gateship creates an isolated worktree, runs the selected implementation session, verifies the acceptance commands, performs an independent read-only review through the same provider, attempting one automatic fix when findings exist, commits and pushes, opens a pull request, squash auto-merges after CI, refreshes origin/main, and releases the clean managed worktree and local branch. An issue with no verify commands fails preflight, and review runs as a fresh session with mechanically read-only capabilities. Container distribution. The multi-architecture image runs through Docker Desktop on Windows and macOS and Docker Engine on Linux, with linux/amd64 and linux/arm64 variants under the same release tag, and contains the compiled binary, git, the GitHub CLI, the Claude Code CLI and the Codex CLI. Both provider CLI releases are pinned, and Claude Code self-updates are disabled in child sessions so a run cannot silently replace the executable behind its recorded workflow revision. Compose publishes the port to loopback only, keeps the image filesystem read-only, provides an ephemeral /tmp, prevents privilege escalation and drops Linux capabilities except those needed for bind mounts with differing host uid. Provider and GitHub authentication happen inside the container on first boot and persist on a named state volume; the selected repository's runtime database and worktrees remain in the project's .gship directory on the projects bind. Recreating the container from the same image and volume returns the same SQLite state, worktrees and logins. Update and recovery guidance in the README calls for a versioned image tag with manifest digest, stopping the service, backing up the state volume and .gship directory, and restoring the previous digest for rollback; gship doctor --json reports architecture, image, volume permissions, Git, gh, Claude, Codex, logins and local connectivity as states without credentials. Security. The HTTP server binds only to 127.0.0.1 by default and browser mutations additionally require a same-origin localhost request; read routes carry no authentication of their own, so the loopback bind is their only boundary. The container image needs a bind-host variable set to 0.0.0.0 for Docker's published-port proxy to reach the service, which moves that boundary to how the port is published on the host; publishing on another interface would expose every unauthenticated read route. The implementer is intentionally write-capable inside the isolated worktree and, in native mode, holds the filesystem authority of the user running Gateship; container mode bounds it to the container and its explicit mounts. The read-only resolver and reviewer restrict Claude to Read, Grep and Glob with MCP and slash commands disabled, and run Codex in its read-only sandbox with user configuration and MCP disabled. Agent and GitHub CLI children receive an environment allowlist, while verification commands are trusted project commands and retain the service environment. Gateship has no web or SQLite field for provider or GitHub credentials; this is process containment for a trusted single operator, not a multi-tenant secret sandbox. Durable state and recovery. Run metadata, provider selection, events, the operator-maintained project brief and one cycle-resolver session id per provider live in a SQLite file under .gship; each run stores its own provider, native session id and worktree path. When the service restarts, an unowned in-flight run becomes interrupted and can be resumed instead of losing the workspace or silently starting a duplicate. After a confirmed merge, Gateship removes the clean managed worktree, its local branch and its stale remote-tracking ref; a failed run releases the same way, except that a branch carrying a commit missing from origin/main is preserved, along with dirty worktrees and unowned leftovers. Cleanup is retried on startup. The runtime source is the remote origin/main ref, fetched before admitting a run and after a merge, and the user's local main branch is intentionally left untouched. Development, community and license. The project builds with Bun and provides commands for type checking, tests, linting and dead-code analysis, with a ship gate that runs the full set before release. Contributions follow the contributing guide, code of conduct and security policy, and external beta users can submit sanitized observations through a documented feedback path that maintainers triage manually. Gateship is released under the MIT license.