Using One Connect

Terminal, containers and databases

Agents and harnesses run natively on your Mac; the project you develop runs in Docker. One Connect gives you project terminals, a scoped Docker workbench, local databases and offline project checks.

What runs where#

One Connect does not install Docker, build images, install dependencies or pull missing images on its own. Provision Docker Desktop and your project's images yourself.

Project terminal#

Terminal and containers (/workspace), and the Terminal tab of the console panel, hold the project's terminals.

• A terminal is an interactive shell running as you. It is not an agent sandbox.
• Each terminal belongs to one project and starts only in that project's repository or one of its own agent worktrees.
• Terminals keep running when you switch projects and reattach with up to 256 KiB of scrollback. Stopping a project closes them.
• Terminal output and keystrokes are never written to disk, especially during vendor sign-in. Structured agent-run logs stay durable and redacted.
• When setup or another page offers you a command, it is placed in a terminal for you to review. It never runs until you press Return.

Docker workbench#

The workbench works only on the project's own Compose binding:

docker compose --project-name <docker_project or name> --project-directory <repo> -f <repo compose file> [-f <generated database file>]

• A container is controlled only if both its Compose project label and its working folder match this repository. Others with the same name are listed as not controlled. Set project.docker_project if your Compose project name differs from project.name.
• It reports whether Docker is installed, running and local, and readiness from real healthchecks: ready, starting, unhealthy, running · no healthcheck, stopped or not created. It also shows missing images, host-port conflicts, and the latest 300 log lines (at most 128 KiB, redacted).
• Actions are refused when Docker points at a non-local endpoint.

Every action needs its own approval#

Start (up --no-deps --no-build --pull never), stop, restart, build, pull and down (volumes kept) each run once, after a two-minute Decision, with an audit event.

The approval binds the Compose file bytes, the selected services' settings, Dockerfiles, build-context entry hashes and executable bits, and the bytes of explicit env, config and secret files. Changing any of them invalidates the request before it runs. Execution uses a private, read-only snapshot of those inputs outside the repository, so later edits in the repository cannot change what was approved. Pull and build also require network approval, and start never builds or pulls. You can always type a command into the project terminal instead.

Supported Compose#

The workbench supports a conservative subset of Compose, so that what you approve is what runs.

• Build contexts and Dockerfiles must be local and inside the repository, with no symlinks, hard links or special files. Contexts are limited to 2,000 entries and 64 MiB; single files to 8 MiB; Compose, Dockerfile, env, config and secret files to 256 KiB.
• .dockerignore supports root-relative literals, *, ?, ** and ordered ! rules.
• Credential and env files, private folders, key and database files, and detected secrets inside a build context are refused.
• Host roots, sockets, external volumes, volume drivers, host namespaces, devices, extra capabilities and privileged services are refused. So are remote build contexts, SSH and secret forwarding, cache exporters, include and extends.
• Compose variable interpolation is refused: use literal values and explicit env files. Escaped container variables ($$VAR) still work.
• Dependencies must be selected explicitly; start and restart never add them.

If the engine restarts during an action, the job is marked interrupted with an unknown exit code. Actions are never replayed.

Local databases#

Local databases generates a project-owned Postgres service (or a SQLite file) in the project's private data: a Compose file, a random password file passed through Docker secrets, and a named volume so data survives restarts and down.

• The plan preview lists the files, the pull and start commands and the connection details. Nothing is written before Create these files, and nothing is pulled or started before each step's approval.
• The password is never displayed, logged, put into prompts or sent to the tracker. Connection info shows <password> and the path of the password file.
• Database names containing "prod" are refused, and the port binds to 127.0.0.1 only.

Project checks in Docker#

After every run and at every merge, the engine re-runs your required checks itself, in Docker, from committed source. Required checks never fall back to the host.

project:
  checks:
    test: cp -R /opt/check-deps/node_modules ./node_modules && npm test
    typecheck: cp -R /opt/check-deps/node_modules ./node_modules && ./node_modules/.bin/tsc --noEmit
  required_checks: [test, typecheck]
  check_runtime:
    mode: docker
    endpoint: unix:///var/run/docker.sock   # your actual local socket
    image: example-app-checks:local         # already installed; resolved to its image ID
    cpus: 1
    memory_mb: 512
    pids: 128
    workspace_mb: 1024
    timeout_seconds: 900

How each check runs:

• Each command gets a fresh, writable copy of the committed Git blobs on the container's tmpfs. Uncommitted and untracked files are excluded.
• The container runs offline, as UID/GID 65534, with a read-only root. Host node_modules, .env, .git, home folders and Docker sockets are never mounted.
• The image must already be installed and contain /bin/sh, cp, the toolchain and every dependency the commands need, at world-readable paths. Images that declare VOLUMEs are refused.
• Output is bounded to 256 KiB and redacted.
• The result records the exact source SHA, the installed image ID, the runtime configuration, exit proof, timeout and a private log path. A check is passed only when the stopped container's process exit is confirmed, and failed cleanup also fails the proof.
• Tracked symlinks, submodules, unsafe paths, sources above 10,000 files or 128 MiB, and images with volumes are reported as unavailable.

Docker Desktop on macOS usually exposes unix:///Users/<you>/.docker/run/docker.sock. Use a local socket, never a remote TCP or SSH context. An optional absolute binary pins the Docker CLI. Arbitrary Docker flags, mounts, privileges and network settings are not accepted.

Try your checks without starting an agent or the daemon:

pnpm acc check --config path/to/control-center.yaml --sha HEAD --log-dir /path/to/check-logs
pnpm acc check --config path/to/control-center.yaml --worktree /path/to/worktree --only test

The command prints a JSON result and exits non-zero when a check failed or was unavailable. Changing the runtime configuration requires fresh check proof before a merge.