Skip to content

Commit 30ebfc8

Browse files
zozo123cursoragent
zozo123
and
cursoragent
committed
docs: add Station profiles security roadmap
Document the Station profile and modelAccess boundaries from issue #193 so future implementation PRs have reviewable phase gates. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 68b6a59 commit 30ebfc8

3 files changed

Lines changed: 134 additions & 0 deletions

File tree

‎docs/features/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ Read when:
6464

6565
- [Sync](sync.md): Git file-list manifests, rsync, fingerprints, excludes, guardrails, and sanity checks.
6666
- [Jobs](jobs.md): named repo-local warmup, hydrate, run, and cleanup workflows.
67+
- [Station profiles](station-profiles.md): planned supervised workload records, agent profile, and model-access security gates.
6768
- [Actions hydration](actions-hydration.md): let GitHub Actions prepare a runner, then sync local work into that workspace.
6869
- [Capsules](capsules.md): local-first replay manifests for GitHub Actions failures.
6970
- [Checkpoints](checkpoints.md): save, restore, and fork reusable remote workspaces.

‎docs/features/station-profiles.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Station Profiles Roadmap
2+
3+
Station profiles are a planned lifecycle primitive for supervised long-running
4+
workloads. They are not implemented in the current CLI: there is no
5+
`crabbox station` command, `stationProfile` config key, or `modelAccess`
6+
credential path yet.
7+
8+
This page records the product and security boundary for
9+
[issue #193](https://github.com/openclaw/crabbox/issues/193) so future PRs can
10+
ship the feature in reviewable pieces.
11+
12+
## Terms
13+
14+
**Station** is the proposed user-facing primitive: a durable supervised workload
15+
record bound to a warm lease. A station is still a Crabbox box; the difference
16+
is that Crabbox records one long-running workload lifecycle instead of only a
17+
single `run` invocation.
18+
19+
**stationProfile** is the proposed config selector for named station policies,
20+
for example `default` or `agent`.
21+
22+
**Agent Station** is shorthand for a station using `stationProfile: agent`.
23+
The agent loop is repo-owned code. Crabbox supervises and records it, but does
24+
not own the prompt loop, planning strategy, model choice, or test
25+
interpretation.
26+
27+
**modelAccess** is the proposed explicit credential-delivery policy for
28+
model/tool access. It must be separate from ordinary `env.allow` forwarding.
29+
30+
Use **reasoning access** only in explanatory copy. It means the repo-owned
31+
workload may run a reasoning loop because a user granted scoped model/tool
32+
access. Crabbox must not expose, judge, store, or reconstruct model reasoning.
33+
34+
## Phase Gates
35+
36+
Ship Station in phases, with separate review for each phase:
37+
38+
1. Generic Station, no model credentials.
39+
2. `agent` station profile, still no model credentials by default.
40+
3. `modelAccess`, only after Station behavior and evidence are stable.
41+
42+
Phase 1 should target SSH-backed lease providers first. Delegated-run providers
43+
should wait until they expose an explicit station-capable contract.
44+
45+
## Phase 1 Contract
46+
47+
A Station is not just `warmup && run --keep` under a new name. The minimum
48+
contract is:
49+
50+
- one durable station id;
51+
- one or more attempts;
52+
- one lease id per attempt;
53+
- one supervisor boot id, pid/start time, command hash, and workdir per
54+
attempt;
55+
- explicit TTL and idle timeout;
56+
- separate lease heartbeat and station heartbeat;
57+
- station-centered status, logs, stop reason, and terminal state;
58+
- idempotent stop that preserves the original terminal reason;
59+
- evidence written on stop, failure, TTL expiry, idle expiry, or lost
60+
supervisor.
61+
62+
Station status should keep `state`, `desiredState`, `attempt`,
63+
`lastObservedAt`, and `stopReason` separate. It should distinguish lease state,
64+
supervisor liveness, command state, and cleanup/revocation state.
65+
66+
## Agent Profile
67+
68+
The first `agent` profile should remain repo-owned and conservative:
69+
70+
```yaml
71+
station:
72+
profiles:
73+
agent:
74+
enabled: true
75+
command: scripts/agent-loop.sh
76+
ttl: 10h
77+
idleTimeout: 45m
78+
restartPolicy: never
79+
```
80+
81+
`restartPolicy` should default to `never`. Agent loops are not safely replayable
82+
by default, so retries are a later product decision.
83+
84+
## modelAccess Security Gates
85+
86+
`modelAccess` must not ship until all of these are true:
87+
88+
- No Crabbox broker, coordinator, cloud provider, or admin credential enters the
89+
station unless explicitly part of the workload policy.
90+
- Only workload-scoped model/tool credentials enter the station.
91+
- Credentials expire at or before station TTL.
92+
- Credentials are scoped, where possible, to repo/org/user, station id, attempt
93+
id, gateway, command hash, allowed models/tools, and budget.
94+
- Credentials are never written to logs, timing JSON, events, compliance
95+
reports, artifacts, screenshots, terminal captures, failure bundles, or
96+
process arguments.
97+
- Evidence records receipts, not secrets: profile, gateway, budget, token
98+
expiry, redaction policy version, issuer, and revocation reason.
99+
- Egress defaults to deny and only allows named approved egress profiles.
100+
- Stop, TTL expiry, idle expiry, budget exhaustion, or compliance failure
101+
revokes credentials before lease teardown.
102+
- Model/tool credentials do not use ordinary repo `env.allow`; they use a
103+
separate audited delivery path.
104+
105+
Do not return stopped `modelAccess` stations to warm pools in v1. Treat them as
106+
dirty by default because they hosted credentialed long-running work.
107+
108+
## Evidence
109+
110+
Station evidence should extend run evidence instead of inventing an unrelated
111+
format. Minimum fields:
112+
113+
- station id, attempt id, lease id, and run id if one exists;
114+
- start and stop timestamps;
115+
- repo SHA, branch, and dirty summary;
116+
- command and shell/argv mode;
117+
- station profile;
118+
- supervisor boot id, pid, start time, and exit status;
119+
- TTL, idle timeout, stop reason, and final state;
120+
- log/event retention limits;
121+
- model access policy and credential receipt metadata, if enabled;
122+
- revocation timestamp and reason, if model access was enabled.
123+
124+
## Non-goals
125+
126+
Station should not add an agent memory database, vector index, semantic judge,
127+
scenario state machine, or model reasoning store to Crabbox core.
128+
129+
Crabbox owns lifecycle, synchronization, supervision, cleanup, credential policy,
130+
logs, artifacts, and evidence. The repo-owned workload owns the brain.

‎docs/security.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,9 @@ Rules:
8989
- `CRABBOX_TAILSCALE_AUTH_KEY` is local direct-provider-only. Do not forward it
9090
to commands, print it, or store it in repo config.
9191
- User config files are written `0600`; `crabbox doctor` reports overly broad local config permissions because broker tokens may be stored there.
92+
- Future `modelAccess` credentials for Station profiles must not use ordinary
93+
repo `env.allow`; they need a separate scoped, auditable, revocable delivery
94+
path. See [Station profiles](features/station-profiles.md).
9295

9396
Project allowlist example:
9497

0 commit comments

Comments
 (0)