@awebai/oats 0.69.11 → 0.69.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +216 -178
- package/bin/oats.mjs +176 -184
- package/docs/capabilities.md +4 -1
- package/docs/configuration.md +63 -5
- package/docs/container.md +246 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +376 -37
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +69 -6
- package/docs/implementation.md +86 -29
- package/docs/integrations.md +9 -5
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/knowledge.md +10 -3
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +42 -8
- package/docs/packages.md +101 -22
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.12.md +97 -0
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/schedules.md +26 -3
- package/docs/servers.md +181 -5
- package/docs/souls-and-instances.md +140 -11
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +30 -5
- package/docs/workspaces.md +32 -6
- package/lib/claim.mjs +21 -5
- package/lib/command-flags.mjs +238 -0
- package/lib/core.mjs +791 -563
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +126 -31
- package/lib/errors.mjs +1 -1
- package/lib/harness-token.mjs +110 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +138 -13
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-listing.mjs +80 -38
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +3 -0
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +119 -27
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +2 -1
- package/lib/servers.mjs +78 -23
- package/lib/session-resume.mjs +68 -53
- package/lib/session-seen.mjs +54 -5
- package/lib/start-env.mjs +13 -7
- package/lib/system-tools.mjs +1 -1
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree.mjs +56 -7
- package/package-catalog.json +3 -3
- package/package.json +2 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +180 -49
- package/lib/tmux-config.mjs +0 -35
package/docs/capabilities.md
CHANGED
|
@@ -693,7 +693,10 @@ instance session they are the session's.
|
|
|
693
693
|
soul-set value from a host-set one there, and never reads `soul.yaml` for it;
|
|
694
694
|
a home with none recorded gives `{}`. A final JSON line may return `meta`,
|
|
695
695
|
`brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
|
|
696
|
-
launch hook's preview answer may add `volatileEnv` (below). A
|
|
696
|
+
launch hook's preview answer may add `volatileEnv` (below). A retire hook's
|
|
697
|
+
`warning` is in the retire's `warnings` and, as a `retire-warning` event, in
|
|
698
|
+
the instance's workspace log, readable with `oats instance events` after the
|
|
699
|
+
home is gone ([Events](desktop-cli-api.md#events)). A **spawn or
|
|
697
700
|
launch hook** may also return an `env` object for the launched process;
|
|
698
701
|
returning `env` from a retire or [worktree](#the-worktree-event) hook is an
|
|
699
702
|
explicit contract error.
|
package/docs/configuration.md
CHANGED
|
@@ -64,7 +64,7 @@ refused (`E_WORKSPACE_SCHEMA`).
|
|
|
64
64
|
| `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
|
|
65
65
|
| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
|
|
66
66
|
| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
|
|
67
|
-
| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). |
|
|
67
|
+
| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). An entry is matched by exact name only, so one whose soul was renamed or moved (a removed package pin, for example) names no soul and keeps nothing off: it fails open, and the soul becomes spawnable again under its new name, unlike a stale `souls.launch` key, which fails closed. Run `oats doctor` after any rename or removal: it reports such an entry as `disabled-soul-unmatched`, with the nearest souls ([what doctor reports](desktop-cli-api.md#launch-preferences)). |
|
|
68
68
|
| `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
|
|
69
69
|
| `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
|
|
70
70
|
| `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
|
|
@@ -289,7 +289,7 @@ instance's terminal and press Enter yourself.
|
|
|
289
289
|
An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
|
|
290
290
|
(a bare name looked up on `PATH`, or a path relative to the directory of the
|
|
291
291
|
file that declares it), `args` (literal, no shell), `env` (a literal string, or
|
|
292
|
-
`{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
|
|
292
|
+
`{ fromEnv: NAME }` or `{ fromFile: /absolute/path }` resolved on the host at start), `model`, `yolo` and
|
|
293
293
|
`default` (0.32; see [the harness default](#the-harness-default)). A launch
|
|
294
294
|
configuration is a host choice: a soul never names one.
|
|
295
295
|
|
|
@@ -450,7 +450,7 @@ launch: { harness: claude, model: claude-opus-5-5 }
|
|
|
450
450
|
souls:
|
|
451
451
|
launch:
|
|
452
452
|
"*": personal # a launch configuration, for every soul here
|
|
453
|
-
oats-expert: { harness: claude, model: claude-opus-5-5 }
|
|
453
|
+
oats-engineering-expert: { harness: claude, model: claude-opus-5-5 }
|
|
454
454
|
oats.engineering/code-reviewer: { harness: codex } # a package soul
|
|
455
455
|
```
|
|
456
456
|
|
|
@@ -552,6 +552,64 @@ source variable must be set on the host (`E_LAUNCH_ENV_MISSING`, before
|
|
|
552
552
|
anything is created or stopped), and only the harness's pane receives it.
|
|
553
553
|
`list` and `preview` redact every environment value, literals included.
|
|
554
554
|
|
|
555
|
+
`{ fromFile: /absolute/path }` reads a regular UTF-8 file on the host that
|
|
556
|
+
starts the harness, at every start. The source is limited to 64 KiB, including
|
|
557
|
+
any final newline; larger files are refused before reading their contents.
|
|
558
|
+
It removes exactly one trailing LF or
|
|
559
|
+
CRLF; an empty file is allowed. Invalid UTF-8 and NUL are refused. A leading
|
|
560
|
+
UTF-8 BOM is preserved as part of the value. `fromFile` is for credential
|
|
561
|
+
values; directory selectors (`HOME`, `PATH`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`,
|
|
562
|
+
`PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`) require a literal or
|
|
563
|
+
`{ fromEnv: NAME }`. A missing, unreadable or
|
|
564
|
+
non-regular file refuses with `E_LAUNCH_ENV_MISSING`. The message names the
|
|
565
|
+
file and the reason (including encoding, NUL or size failures), then names
|
|
566
|
+
`oats harness token set <harness> --server <id>` or operator provisioning on
|
|
567
|
+
that host. The token command is a separate provisioning feature.
|
|
568
|
+
|
|
569
|
+
```yaml
|
|
570
|
+
launch-configs:
|
|
571
|
+
subscription:
|
|
572
|
+
harness: claude
|
|
573
|
+
env:
|
|
574
|
+
CLAUDE_CODE_OAUTH_TOKEN: { fromFile: /etc/agent-login/claude-token }
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
For server credentials, [harness token commands](servers.md#harness-credentials)
|
|
578
|
+
deliver an existing setup-token or API key through the separate operator
|
|
579
|
+
route, with `--stdin`. Bind the receiver's server-side file in the launch
|
|
580
|
+
configuration, for example
|
|
581
|
+
`CLAUDE_CODE_OAUTH_TOKEN: { fromFile: /srv/oats-team/team/login/claude-token }`.
|
|
582
|
+
For Codex use `OPENAI_API_KEY`; for pi use the selected provider's env
|
|
583
|
+
variable. The token command does not choose a provider or edit this binding.
|
|
584
|
+
A replacement is read at the next start; existing sessions are not restarted.
|
|
585
|
+
|
|
586
|
+
**Claude login credentials.** At a Claude start, OATS checks for
|
|
587
|
+
`$CLAUDE_CONFIG_DIR/.credentials.json`, or `$HOME/.claude/.credentials.json`
|
|
588
|
+
when no config directory is selected, using the launch's effective environment.
|
|
589
|
+
If OATS sets `CLAUDE_CODE_OAUTH_TOKEN` through a literal, either reference kind,
|
|
590
|
+
or a capability's launch contribution, it refuses with
|
|
591
|
+
`E_CLAUDE_LOGIN_CREDENTIAL`, naming the exact credential file it found. An
|
|
592
|
+
empty value counts. Remove the `/login`
|
|
593
|
+
credential from that Claude configuration and use `oats harness token set
|
|
594
|
+
claude` to provision an inference-only token. Without an OATS-set token, a
|
|
595
|
+
personal `/login` credential is allowed silently. An inherited token does not
|
|
596
|
+
select the token route.
|
|
597
|
+
Other harnesses are unaffected. Spawn preview and apply check the predictable
|
|
598
|
+
configuration before creating a home, worktree or identity. A selector supplied
|
|
599
|
+
by a capability hook is checked after its launch environment is known, and
|
|
600
|
+
every actual launch checks its final pane again. On macOS, Claude's `/login`
|
|
601
|
+
credential lives in the Keychain; this file check does not inspect it.
|
|
602
|
+
|
|
603
|
+
Both reference kinds use `OATS_LAUNCH_REF_<NAME>` aliases. Their values are
|
|
604
|
+
absent from process arguments, tmux command lines, recipes, events and logs.
|
|
605
|
+
The kernel hands them to the pane through a per-start file in the instance
|
|
606
|
+
home, created exclusively with mode 0600; the launcher reads and deletes it
|
|
607
|
+
before executing the pane command. A failed dispatch removes it. Retirement
|
|
608
|
+
recovery excludes leftover handoff files. Each subsequent start removes
|
|
609
|
+
abandoned handoffs before dispatch, even when the new launch has no references. The start environment records only
|
|
610
|
+
keyed digests of reference values, including file references, so a resume
|
|
611
|
+
refuses a changed value; an ordinary start adopts a rotated file.
|
|
612
|
+
|
|
555
613
|
**The instance's `oats`.** Every launch (`oats spawn`, `session start`,
|
|
556
614
|
`session restart`, locally or through `--server`) writes `<home>/.oats/bin/oats`,
|
|
557
615
|
a link to the launching kernel's `bin/oats.mjs`, and runs the harness with
|
|
@@ -693,8 +751,8 @@ oats doctor # this deployment's files and the lock
|
|
|
693
751
|
```
|
|
694
752
|
|
|
695
753
|
Environment: `OATS_REMOTE_CACHE` relocates the fetch cache (which also holds
|
|
696
|
-
the bounded parsed-read cache
|
|
697
|
-
it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
|
|
754
|
+
the bounded parsed-read cache, the observations `--max-age` reuses and the
|
|
755
|
+
records of verified package trees; all of it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
|
|
698
756
|
catalog file. The read verbs (`status`, `workspace status`, `souls`,
|
|
699
757
|
`capabilities`, `inspect`, the read forms of `teams` and `soul teams`, and
|
|
700
758
|
`spawn --preview`), and a spawn apply bound by `--expect-decision`, take
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
# Agent team container
|
|
2
|
+
|
|
3
|
+
`container/agent/` supplies an agent image and a Compose service for one
|
|
4
|
+
team's trust group. It runs non-root sshd on port 2222; the operator uses the
|
|
5
|
+
existing [server route](servers.md) to connect, preview and spawn. The
|
|
6
|
+
entrypoint creates private state directories and host keys, then starts
|
|
7
|
+
sshd. Deployment setup and seat admission belong to the operator.
|
|
8
|
+
|
|
9
|
+
## Configuration contract
|
|
10
|
+
|
|
11
|
+
The same inputs apply to a Compose service or a platform's container spec:
|
|
12
|
+
|
|
13
|
+
| Input | Purpose |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| Deployment repository and commit | Operator provisions `/state/deploy`; its `oats-lock.json` pins packages and souls. Record the source and lock commits in the receipt. |
|
|
16
|
+
| aweb/AWID endpoints and team identifier | Deployment configuration; the platform's egress allowlist admits the endpoints. |
|
|
17
|
+
| Operator SSH public key | Read-only `authorized_keys` mount. |
|
|
18
|
+
| Resource limits | Runtime pids, memory and CPU limits. |
|
|
19
|
+
| Approved mounts | Explicit list, checked against the running container. |
|
|
20
|
+
| Egress destination list | Platform's resolver/forwarder configuration, outside the agent container. |
|
|
21
|
+
| Harness launch environment | Non-secret literals or file references, resolved at process start. |
|
|
22
|
+
|
|
23
|
+
Credentials never go in the image, build arguments, Compose environment, env
|
|
24
|
+
files or OATS configuration literals. The operator provisions ordinary
|
|
25
|
+
member seats and an inference-only Claude setup-token. Team/controller keys,
|
|
26
|
+
owner authority and service credentials stay outside the container. A
|
|
27
|
+
`/login` credential or a copy of `~/.claude` must never enter it.
|
|
28
|
+
|
|
29
|
+
## Build and upgrade
|
|
30
|
+
|
|
31
|
+
From a checkout at the reviewed commit:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
env -i PATH="$PATH" docker build --platform linux/arm64 \
|
|
35
|
+
-t oats-agent:reviewed container/agent
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Use `linux/amd64` on the target builder. The Dockerfile pins Node 22 Debian
|
|
39
|
+
Bookworm slim by its multi-architecture index digest; the committed
|
|
40
|
+
`package.json` and `package-lock.json` pin the CLI versions and npm integrity
|
|
41
|
+
hashes. `npm ci --ignore-scripts` installs the dependency closure. Only
|
|
42
|
+
`@awebai/aw` is rebuilt with lifecycle scripts, in a build step without a
|
|
43
|
+
network. Claude's matching native binary is linked directly from its locked
|
|
44
|
+
platform package, without running its installer. Each CLI's version command
|
|
45
|
+
must succeed during the build.
|
|
46
|
+
|
|
47
|
+
`libnss-wrapper` is the extra OS package needed for arbitrary UID support.
|
|
48
|
+
No credentials or SSH host keys are baked in. The build context allowlist
|
|
49
|
+
excludes everything except the image's five inputs.
|
|
50
|
+
|
|
51
|
+
A derived image may add reviewed OS tools with `USER root` and `RUN`, then
|
|
52
|
+
restore `USER agent`. Those build steps use the system passwd/group database.
|
|
53
|
+
The entrypoint enables nss_wrapper only after generating the runtime
|
|
54
|
+
database; SSH command environments also enable it. An overridden entrypoint
|
|
55
|
+
or `docker exec` uses system NSS, so an arbitrary numeric UID may have no
|
|
56
|
+
name there. Use the SSH route for commands that require the `agent` mapping.
|
|
57
|
+
|
|
58
|
+
CLIs upgrade only by building and selecting a new image. Global npm installs
|
|
59
|
+
fail on the read-only root. To update the OATS pin, change its one dependency
|
|
60
|
+
version and regenerate this directory's lock with
|
|
61
|
+
`npm install --package-lock-only --ignore-scripts`; review both files. Do not
|
|
62
|
+
use `--install-oats` or `--install-aw` against a running container.
|
|
63
|
+
|
|
64
|
+
The committed OATS 0.69.12 pin supports container/SSH checks and spawn
|
|
65
|
+
preview. Live token delivery requires a new pin to a release that includes
|
|
66
|
+
`env: { fromFile: ... }` and the operator's `oats harness token set` route.
|
|
67
|
+
Until that image is built, the two-seat inference milestone remains unproven.
|
|
68
|
+
|
|
69
|
+
## Mounts and UID
|
|
70
|
+
|
|
71
|
+
The provisioner creates host directories with the runtime UID and GID.
|
|
72
|
+
The Compose defaults are `20001:20001`; use an explicit non-root UID:GID in
|
|
73
|
+
the target service so the group-readable token is readable.
|
|
74
|
+
|
|
75
|
+
The image also starts with a numeric UID alone, such as
|
|
76
|
+
`docker run --user 20001`. When that UID has no image passwd entry, Docker
|
|
77
|
+
assigns GID 0. The wrapper names that runtime group `agent`, and new files
|
|
78
|
+
in `/state` have GID 0. Such a run cannot read a root:20001 0750 login
|
|
79
|
+
directory or its 0440 token. Use `--user 20001:20001` for the team login;
|
|
80
|
+
the UID-only form proves startup and SSH support, not token access.
|
|
81
|
+
|
|
82
|
+
| Container path | Host ownership and mode | Access |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| `/state` | Runtime UID:GID, 0700 | Read/write; persistent |
|
|
85
|
+
| `/work` (optional) | Runtime UID:GID, 0700 | Read/write |
|
|
86
|
+
| `/etc/agent-login` | root:runtime-GID, 0750; `claude-token` root:runtime-GID, 0440 | Read-only |
|
|
87
|
+
| `/etc/agent-ssh/authorized_keys` | root-owned regular file, 0644 | Read-only |
|
|
88
|
+
| `/etc/resolv.conf` | Operator-provided resolver file | Read-only |
|
|
89
|
+
| `/tmp` | tmpfs, rw,nosuid,nodev,mode=1777 | Ephemeral |
|
|
90
|
+
|
|
91
|
+
All binds use `create_host_path: false`: a missing path fails startup.
|
|
92
|
+
`/state/home`, `/state/ssh` and `/state/deploy` are created 0700 by the agent.
|
|
93
|
+
`HOME=/state/home`. nss_wrapper reads passwd/group files generated in
|
|
94
|
+
`/state/ssh`, mapping the name `agent` to the actual UID/GID. The root
|
|
95
|
+
filesystem and `/etc/passwd` remain read-only. SSH sessions receive the same
|
|
96
|
+
mapping and HOME. The `agent` user has no sudo.
|
|
97
|
+
|
|
98
|
+
Host keys persist in `/state/ssh`; agents in the trust group can read them.
|
|
99
|
+
sshd accepts only `agent` public-key authentication, with PAM, password and
|
|
100
|
+
keyboard-interactive authentication off. Forwarding is disabled: OATS's
|
|
101
|
+
ControlMaster multiplexing uses SSH command/session channels and needs no
|
|
102
|
+
TCP, agent or X11 forwarding. The operator's jump host must separately permit
|
|
103
|
+
the ProxyJump connection to the container.
|
|
104
|
+
|
|
105
|
+
## Compose integration
|
|
106
|
+
|
|
107
|
+
Supply these plain variables to the bundle's env file:
|
|
108
|
+
|
|
109
|
+
| Variable | Meaning |
|
|
110
|
+
| --- | --- |
|
|
111
|
+
| `TEAM` | Container name suffix: `oats-agent-${TEAM}`; service key is `agent`. |
|
|
112
|
+
| `AGENT_IMAGE` | Reviewed image tag or digest. |
|
|
113
|
+
| `AGENT_UID`, `AGENT_GID` | Runtime IDs; both default to 20001. |
|
|
114
|
+
| `TEAM_STATE_DIR` | Absolute host directory for `/state`. |
|
|
115
|
+
| `TEAM_WORK_DIR` | Optional absolute host directory for `/work`. |
|
|
116
|
+
| `TEAM_LOGIN_DIR` | Absolute host directory containing `claude-token`. |
|
|
117
|
+
| `AUTHORIZED_KEYS_FILE` | Absolute host public-key file. |
|
|
118
|
+
| `RESOLV_CONF_FILE` | Absolute host resolver file; always required. |
|
|
119
|
+
| `AGENT_PIDS`, `AGENT_MEMORY`, `AGENT_CPUS` | Positive limits; memory uses bytes, k, m or g. |
|
|
120
|
+
| `AGENTS_NETWORK`, `AGENT_IP` | Installer-created external network and container address. |
|
|
121
|
+
|
|
122
|
+
The bundle owns the network, resolver, forwarder, firewall and their bypass
|
|
123
|
+
checks. The agent service publishes no ports and sets no DNS or extra-hosts
|
|
124
|
+
override. It joins only the named external `agents` network. Its restart
|
|
125
|
+
policy is `unless-stopped`; security flags are fixed in the service file.
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
|
|
129
|
+
-f compose.yaml -f container/agent/compose.agent.yaml config
|
|
130
|
+
docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
|
|
131
|
+
-f compose.yaml -f container/agent/compose.agent.yaml up -d
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
When `TEAM_WORK_DIR` is set, append
|
|
135
|
+
`-f container/agent/compose.agent.work.yaml` to both commands. Otherwise omit
|
|
136
|
+
the override: the base has no `/work` mount. With multiple Compose files,
|
|
137
|
+
paths resolve relative to the first file; use absolute host paths. Container
|
|
138
|
+
down/upgrade preserves `/state`; the operator owns provisioning and rollback.
|
|
139
|
+
|
|
140
|
+
## OATS over SSH
|
|
141
|
+
|
|
142
|
+
The operator's SSH alias selects the key, host-key verification, port 2222
|
|
143
|
+
and jump route. The equivalent connection is:
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
ssh -J <provisioner>@<host> -p 2222 agent@<container-ip>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Register an already provisioned deployment, or connect it from the operator's
|
|
150
|
+
deployment using its source reference:
|
|
151
|
+
|
|
152
|
+
```sh
|
|
153
|
+
oats server add team-agent --ssh <ssh-alias> --workspace /state/deploy \
|
|
154
|
+
--oats /usr/local/bin/oats --path /usr/local/bin:/usr/bin:/bin
|
|
155
|
+
oats server connect team-agent --ssh <ssh-alias> --dir /state/deploy \
|
|
156
|
+
--oats /usr/local/bin/oats --path /usr/local/bin:/usr/bin:/bin
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Use public HTTPS package pins unless a separate reviewed credential route
|
|
160
|
+
is provisioned. Verify `server connect` reports ready. The operator places
|
|
161
|
+
two independently admitted ordinary-member identities at
|
|
162
|
+
`/state/seats/<alias>/.aw`; each spawn selects one:
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
oats spawn <soul> --server team-agent --harness claude --preview --provider oats.aweb identity.source=/state/seats/<alias>/.aw
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Preview runs no provider hook and does not validate a missing seat. Apply
|
|
169
|
+
only after reviewing it and provisioning its seat; use the same arguments
|
|
170
|
+
without `--preview`. Keep the team and controller keys outside the container.
|
|
171
|
+
|
|
172
|
+
On an OATS release supporting file-backed launch environment, the launch
|
|
173
|
+
configuration uses:
|
|
174
|
+
|
|
175
|
+
```yaml
|
|
176
|
+
launch-configs:
|
|
177
|
+
team-claude:
|
|
178
|
+
harness: claude
|
|
179
|
+
env:
|
|
180
|
+
CLAUDE_CONFIG_DIR: /state/home/.claude
|
|
181
|
+
CLAUDE_CODE_OAUTH_TOKEN:
|
|
182
|
+
fromFile: /etc/agent-login/claude-token
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Select it with `--launch-config team-claude`. The operator provisions only a
|
|
186
|
+
`claude setup-token` result through the supported token route. It is readable
|
|
187
|
+
by every agent in the same trust group; read-only mounting does not hide it
|
|
188
|
+
or narrow its authority. Never share the mount across trust groups.
|
|
189
|
+
|
|
190
|
+
## Acceptance and evidence
|
|
191
|
+
|
|
192
|
+
The host needs Docker and Node 22+. Export the same plain variables used for
|
|
193
|
+
Compose, then run:
|
|
194
|
+
|
|
195
|
+
```sh
|
|
196
|
+
container/agent/accept.sh "oats-agent-${TEAM}" --evidence local
|
|
197
|
+
container/agent/accept.sh "oats-agent-${TEAM}" --evidence target-amd64
|
|
198
|
+
container/agent/accept.sh "oats-agent-${TEAM}" --evidence live-lab \
|
|
199
|
+
--claude /state/deploy/agents/<soul>/instances/<instance>
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Choose the label matching the actual run. `local` accepts the builder's
|
|
203
|
+
architecture; the other labels require amd64 and root:GID 0440 token / 0750
|
|
204
|
+
login-directory metadata. Local fixtures use a dummy file, never a real
|
|
205
|
+
login. Run the live Claude mode separately for each admitted instance home;
|
|
206
|
+
the home is an evidence label and an `instance.json` existence check. The
|
|
207
|
+
probe runs from a private temporary directory under `/tmp`, removed on
|
|
208
|
+
success or failure, with `--setting-sources user`. It uses the container's
|
|
209
|
+
user settings, excluding the instance's project settings, hooks and
|
|
210
|
+
`CLAUDE.md`, so the probe does not clear that live instance's waiting claim.
|
|
211
|
+
It reads the token only inside the container and requires the exact inference
|
|
212
|
+
response. It records no raw Claude output.
|
|
213
|
+
|
|
214
|
+
The script compares inspect settings and the exact bind list to the exported
|
|
215
|
+
variables. It resolves `AGENT_IMAGE` independently and requires that image's
|
|
216
|
+
ID, reference and start command, and its complete environment (printing only
|
|
217
|
+
names of differing variables). Other comparisons include supplementary
|
|
218
|
+
groups, namespace overrides, sysctls, published ports, resolver overrides
|
|
219
|
+
and the single network/address. The OCI runtime must match the daemon's
|
|
220
|
+
independently read default; shared memory stays at Docker's 64 MiB default,
|
|
221
|
+
the OOM killer stays enabled, and device cgroup rules stay empty. The total
|
|
222
|
+
memory-plus-swap setting is absent or Docker's default of twice the memory
|
|
223
|
+
limit; unlimited swap is refused.
|
|
224
|
+
It checks the process's UID/GID/supplementary groups/capabilities/no-new-privileges
|
|
225
|
+
and non-root sshd's banner, scans `/` as container root (pruning `/proc`,
|
|
226
|
+
`/sys`, `/dev` and the agent-scanned `/state`, `/tmp`, `/run`, `/work`),
|
|
227
|
+
and scans those trees plus writable `/dev/shm` and `/dev/mqueue` as the agent
|
|
228
|
+
for `.credentials.json`. It checks
|
|
229
|
+
the token is readable and not writable, and proves a global npm install fails using an
|
|
230
|
+
offline local package. Scan errors fail acceptance. The root inspection
|
|
231
|
+
process receives no added capabilities. Token provenance still needs the
|
|
232
|
+
operator's receipt: permissions and successful inference cannot distinguish
|
|
233
|
+
all credential classes.
|
|
234
|
+
|
|
235
|
+
A successful script run covers those checks only. The complete platform
|
|
236
|
+
receipt also needs `server connect`, both admitted-seat spawn previews and
|
|
237
|
+
applies, the source/lock commit, viewer, package sync, the bundle's network
|
|
238
|
+
and bypass evidence, mail/chat exchange, governance refusals and any broker
|
|
239
|
+
checks. Record target evidence separately from local evidence. Container
|
|
240
|
+
startup and a local preview do not establish two running agents.
|
|
241
|
+
|
|
242
|
+
`test/agent-container.test.mjs` pins the image, Compose and SSH security
|
|
243
|
+
settings and rejects weakened inspect fixtures. The SSH guard requires flat
|
|
244
|
+
`Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
|
|
245
|
+
equals-delimited keywords and quoted keywords. Follow the repository's
|
|
246
|
+
local check limits; full suites run in CI.
|
|
@@ -294,6 +294,8 @@ Each entry's manifests, souls and integrity are read at the observed commit →
|
|
|
294
294
|
`{ lock, changes: [{ id, from, to, commit }] }` (`to: null`: no longer declared).
|
|
295
295
|
|
|
296
296
|
- A branch is `E_PACKAGE_INTEGRITY { why: "branch" }`.
|
|
297
|
+
- A manifest whose `package` is not the entry's key is `E_PACKAGE_INTEGRITY { why: "package-id" }`,
|
|
298
|
+
fresh or already locked.
|
|
297
299
|
- An unchanged version, source and path is re-verified: a moved commit or different integrity,
|
|
298
300
|
capabilities or souls is `E_PACKAGE_INTEGRITY`.
|
|
299
301
|
- A malformed package is `E_PACKAGE_MANIFEST`.
|