Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Outer: agent working agreement

Outer is a personal software forge for AI agents. An agent talks MCP to Outer, Outer builds the user's Ilha + Void app and runs it on [celld](https://celld.dev), and serves it at `https://<slug>.outer.now`.
Outer is a personal software forge for AI agents. An agent talks MCP to Outer, Outer builds the user's Ilha + Void app and runs it on [Cello](https://cello.ryuz.eu), and serves it at `https://<slug>.outer.now`.

- **Design record:** the maintainer's spec at `~/Developer/vault/outer/spec.md` (not in this repo). Read it before changing behavior, and say so when a change departs from it.
- **Status:** live at `outer.now` (M0 done); milestone M1 (owner alpha) in progress.
Expand Down Expand Up @@ -45,7 +45,7 @@ is `crates/outer/tests/hostile.rs`, in two layers:
and the harness refuses to pass unless the installed `inet outer` table
covers the probe uid.

The `worker.js` `/probes` check needs a live celld fleet with a deployed app
The `worker.js` `/probes` check needs a live Cello fleet with a deployed app
and stays a manual VPS step (see the script header). A PR that changes escape
relevant behavior adds a fixture probe first, then the containment.

Expand All @@ -59,7 +59,7 @@ relevant behavior adds a fixture probe first, then the containment.
| `crates/outer/src/http/` | Axum router: operator probes on the platform host, app proxy fallback for app hosts |
| `crates/outer/src/store/` | `Store` (R2 over S3, or in-memory) and the SQLite snapshot to the bucket |
| `crates/outer/src/git/` | Each app's repo: a bucket WAL (tip bundle + `MANIFEST.json`) and worktree-free commits |
| `crates/outer/src/fleet/` | Sandboxed processes, cgroup v2 leaves, nft egress rules, the celld supervisor |
| `crates/outer/src/fleet/` | Sandboxed processes, cgroup v2 leaves, nft egress rules, the Cello supervisor |
| `e2e/hostile/`, `crates/outer/tests/hostile.rs` | Hostile suite (§12.7): fixtures, manifest, two-layer harness |
| `scripts/hostile-suite.sh` | Integrator entry for the privileged hostile layer (VPS) |
## Rules
Expand Down
16 changes: 8 additions & 8 deletions crates/outer/tests/hostile.rs
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
//! cgroupfs delegation, the nft table, a JS runtime, scoped R2 creds) is
//! absent, so a dev machine never passes vacuously.
//!
//! The worker fixture (`e2e/hostile/worker.js`) needs a live celld fleet
//! The worker fixture (`e2e/hostile/worker.js`) needs a live cello fleet
//! with a deployed app, which no test here can conjure without a bucket; it
//! runs as a documented manual step in `scripts/hostile-suite.sh`.

Expand Down Expand Up @@ -225,10 +225,10 @@ fn hostile_fleet_grants_cannot_publish_a_deployment() {
let [(data_permission, data), (deploy_permission, deploy)] = grants;
assert_eq!(data_permission, Permission::ReadWrite);
assert_eq!(deploy_permission, Permission::ReadOnly);
// The exact state namespaces, a cross-repo contract with celld: any
// The exact state namespaces, a cross-repo contract with cello: any
// runtime write outside these is a failed write, and any list wider
// than this (in particular anything covering `deploy/`) is a publish
// hole. `node-cells/` and the non-terminated `wake-` are celld's dead
// hole. `node-cells/` and the non-terminated `wake-` are cello's dead
// node GC and legacy wake guard.
assert_eq!(
data,
Expand Down Expand Up @@ -290,7 +290,7 @@ fn hostile_platform_env_never_reaches_apps() {
"AWS_SECRET_ACCESS_KEY",
"AWS_SESSION_TOKEN",
"S3_ENDPOINT",
"CELLD_WATCH",
"CELLO_WATCH",
"OUTER_SECRET",
"OUTER_R2_BUCKET",
"CLOUDFLARE_API_TOKEN",
Expand All @@ -316,7 +316,7 @@ fn hostile_platform_env_never_reaches_apps() {
}

/// The fleet command binds loopback only and drops reserved names from app
/// env: a worker that fetches the celld internal listener or another fleet's
/// env: a worker that fetches the cello internal listener or another fleet's
/// port from its own environment finds nothing to aim at, and the platform
/// secrets the supervisor holds never enter the fleet's environment.
#[test]
Expand Down Expand Up @@ -346,15 +346,15 @@ fn hostile_fleet_command_is_loopback_only_and_scoped() {
],
};
let opts = outer::fleet::supervisor::FleetOpts {
celld_bin: "celld".to_string(),
cello_bin: "cello".to_string(),
state_dir: PathBuf::from("/data/fleets/hostile"),
shutdown_total_ms: 5000,
idle_evict_secs: 60,
deploy_poll_secs: 300,
asset_cache_mb: 256,
};
let (program, args, env) = outer::fleet::supervisor::fleet_command(&spec, &opts);
assert_eq!(program, "celld");
assert_eq!(program, "cello");
for flag in ["--listen", "--internal-listen"] {
let at = args.iter().position(|arg| arg == flag).expect(flag);
let addr = &args[at + 1];
Expand Down Expand Up @@ -816,7 +816,7 @@ async fn hostile_build_probes_are_contained() {
/// round-trips inside one and must be refused (403/401, never 404 or a
/// transport error) on a sibling prefix, the bucket root, and the deploy
/// pointer (`deploy/current.json`), because the node reads deployments with
/// its separate read-only `CELLD_DEPLOY_AWS_*` grant. The probe then uses
/// its separate read-only `CELLO_DEPLOY_AWS_*` grant. The probe then uses
/// that deploy grant (`HOSTILE_S3_DEPLOY_*`) to LIST and GET under
/// `deploy/` (must succeed) and to PUT there (must be refused). Needs
/// `HOSTILE_S3_*` env with both grants, minted by the integrator on the VPS
Expand Down
2 changes: 1 addition & 1 deletion e2e/hostile/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
{ "id": "fetch:loopback-target", "phase": "build", "category": "blocked-egress", "must": "fail", "desc": "Build cannot reach a live loopback listener (fail-closed: the harness proves it serves)" },
{ "id": "fetch:internet", "phase": "build", "category": "blocked-egress", "must": "succeed", "desc": "Positive control: ordinary internet egress still works" },
{ "id": "fetch:neighbour-fleet", "phase": "worker", "category": "fleet-ports", "must": "fail", "desc": "Worker cannot fetch another fleet's public port" },
{ "id": "fetch:platform-internal", "phase": "worker", "category": "fleet-ports", "must": "fail", "desc": "Worker cannot fetch outer's loopback / celld internal ports" },
{ "id": "fetch:platform-internal", "phase": "worker", "category": "fleet-ports", "must": "fail", "desc": "Worker cannot fetch outer's loopback / cello internal ports" },
{ "id": "fetch:metadata", "phase": "worker", "category": "blocked-egress", "must": "fail", "desc": "Worker cannot reach the cloud metadata IP" },
{ "id": "fetch:smtp-worker", "phase": "worker", "category": "blocked-egress", "must": "fail", "desc": "Worker cannot open SMTP ports" },
{ "id": "env:worker-secrets", "phase": "worker", "category": "host-secrets", "must": "fail", "desc": "No platform secret names in the worker env" },
Expand Down
2 changes: 1 addition & 1 deletion e2e/hostile/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "outer-hostile-fixture",
"private": true,
"version": "1.0.0",
"description": "Hostile tenant fixture for the §12.7 hostile suite: a celld worker plus build/release probes that try to escape. See manifest.json and scripts/hostile-suite.sh.",
"description": "Hostile tenant fixture for the §12.7 hostile suite: a cello worker plus build/release probes that try to escape. See manifest.json and scripts/hostile-suite.sh.",
"scripts": {
"build": "node ./build-probe.mjs",
"release": "node ./r2-probe.mjs"
Expand Down
6 changes: 3 additions & 3 deletions e2e/hostile/r2-probe.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// - the *state* credential (HOSTILE_S3_KEY/SECRET): read-write over the
// state prefixes and NOT over `deploy/` or `deploy-blobs/`;
// - the *deploy* credential (HOSTILE_S3_DEPLOY_KEY/SECRET): read-only over
// `deploy/` and `deploy-blobs/` (the node's CELLD_DEPLOY_AWS_* grant).
// `deploy/` and `deploy-blobs/` (the node's CELLO_DEPLOY_AWS_* grant).
// So the state positive control round-trips inside a state prefix and a
// write to the deployment pointer must be refused, while the deploy grant
// reads `deploy/` and a write with it is refused too.
Expand Down Expand Up @@ -40,7 +40,7 @@ const token = process.env.HOSTILE_S3_TOKEN ?? "";
const ownPrefix = need("HOSTILE_S3_PREFIX").replace(/^\//, "");
const siblingPrefix = (process.env.HOSTILE_S3_SIBLING ?? "fleets/hostile-neighbour/").replace(/^\//, "");
const dataPrefix = (process.env.HOSTILE_S3_DATA_PREFIX ?? `${ownPrefix}cells/`).replace(/^\//, "");
// The node's read-only deployment grant (`CELLD_DEPLOY_AWS_*`): it must
// The node's read-only deployment grant (`CELLO_DEPLOY_AWS_*`): it must
// read `deploy/` and `deploy-blobs/` but can never publish. The object the
// GET probe reads is uploaded by the integrator with the bucket root keys.
const deployAccess = need("HOSTILE_S3_DEPLOY_KEY");
Expand Down Expand Up @@ -113,7 +113,7 @@ try {
}

// The deployment artifacts are read-only for a fleet: the node's
// `CELLD_DEPLOY_AWS_*` grant must list and get `deploy/` and can never
// `CELLO_DEPLOY_AWS_*` grant must list and get `deploy/` and can never
// publish. The positive read proves the grant is the deploy one, not a
// state key; the refused write is the boundary under test.
try {
Expand Down
6 changes: 3 additions & 3 deletions e2e/hostile/worker.js
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
// Hostile app worker (celld): serves its build/r2 probe results as JSON and
// Hostile app worker (cello): serves its build/r2 probe results as JSON and
// runs the Worker-side network probes live. Every probe must fail except
// internet egress. Borrowed from Noite's apps/noite/test/hostile/index.js:
// Outer drops the Caddy/runner/control-port targets and aims at Outer's own
// loopback surface instead (neighbour fleet ports, outer's proxy port, the
// celld internal listener). Query: /probes?neighbour=<port>&platform=<port>.
// cello internal listener). Query: /probes?neighbour=<port>&platform=<port>.
import buildProbes from "./dist/probe.json";
import releaseProbes from "./dist/release-probe.json";

Expand Down Expand Up @@ -36,7 +36,7 @@ export default {
);
worker[n1] = v1;

// Outer's own loopback surface (proxy port, celld internal listener):
// Outer's own loopback surface (proxy port, cello internal listener):
// unreachable from a tenant uid under the nft policy.
const [n2, v2] = await attempt("fetch:platform-internal", () =>
timedFetch(`http://127.0.0.1:${platform}/`)
Expand Down
2 changes: 1 addition & 1 deletion scripts/hostile-probe-vps.sh
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ for planted in "OUTER_SECRET planted" "STRIPE_SECRET_KEY planted" "AWS_SECRET_AC
set -- $planted
case "$1" in
PORT|HOST|NODE_OPTIONS) continue ;;
AWS_*|S3_*|CELLD_*|OUTER_*|CLOUDFLARE_*|R2_*|STRIPE_*|RESEND_*|JEV_*|LD_*|BUN_*)
AWS_*|S3_*|CELLD_*|CELLO_*|OUTER_*|CLOUDFLARE_*|R2_*|STRIPE_*|RESEND_*|JEV_*|LD_*|BUN_*)
[ "$1" = "BUN_INSTALL_CACHE_DIR" ] || continue ;;
esac
putenv "$1" "$2"
Expand Down
2 changes: 1 addition & 1 deletion scripts/hostile-suite.sh
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@
# HOSTILE_S3_DEPLOY_KEY HOSTILE_S3_DEPLOY_SECRET
# HOSTILE_S3_DEPLOY_TOKEN HOSTILE_S3_DEPLOY_PREFIX (=<prefix>deploy/)
# HOSTILE_S3_DEPLOY_OBJECT (default <prefix>deploy/hostile-probe.json)
# - Worker layer (manual, needs celld + a bucket): deploy the fixture as
# - Worker layer (manual, needs cello + a bucket): deploy the fixture as
# two apps (`hostile`, `hostile-neighbour`), then
# curl 'https://hostile.<apps-domain>/probes?neighbour=<port>&platform=<port>'
# and confirm every worker probe is contained except `fetch:internet`.
Expand Down
4 changes: 2 additions & 2 deletions web/blume.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ export default defineConfig({
{ from: "/guides/ilha", to: "/agents/frontend/ilha", status: 301 },
{ from: "/guides/void", to: "/agents/frontend/void", status: 301 },
{ from: "/guides/website", to: "/agents/frontend/website", status: 301 },
{ from: "/guides/celld", to: "/agents/platform/celld", status: 301 },
{ from: "/guides/moderation", to: "/agents/security/moderation", status: 301 },
{ from: "/guides/celld", to: "/agents/platform/cello", status: 301 },
{ from: "/agents/platform/celld", to: "/agents/platform/cello", status: 301 },
{ from: "/guides/limits", to: "/agents/platform/limits", status: 301 },
{ from: "/guides/storage", to: "/agents/backend/files", status: 301 },
{ from: "/guides/export", to: "/agents/deploy/export", status: 301 },
Expand Down
2 changes: 1 addition & 1 deletion web/docs/STYLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ One term per concept. Left column wins everywhere.
| plan (Free / Pro) | tier, subscription (as plan name) | Capitalized plan names. |
| quota | limit (for counted resources) | Code changes, apps, collaborators. `limits` only for the Deploy page title and hard technical caps. |
| preview deploy | staging, branch deploy | One per app, Pro, at `<slug>--preview.outer.now`. |
| fleet | server, container, instance | The celld worker pool an app runs on. |
| fleet | server, container, instance | The Cello worker pool an app runs on. |
| binding | integration, env (for config) | `d1_databases`, `kv_namespaces`, declared in `void.config.ts`. |
| secret | env var, token (for stored keys) | Set outside code, read as `env.MY_KEY`. |
| agent | bot, assistant (for the builder) | The AI building the app over MCP. |
Expand Down
4 changes: 2 additions & 2 deletions web/docs/agents/backend/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The template ships with D1 on by default. Copy `pages/index.server.ts`: a loader
d1_databases: [{ binding: "DB", database_name: "app-db" }],
```

One D1 database and one R2 bucket per app: a second `d1_databases` entry fails the deploy at validation ("Outer apps can have one D1 database and one R2 bucket for now; merge the extra ones"). The built `dist/wrangler.json` carries the binding to celld, which creates the database on first use. Celld keys the database by name, so a typo opens a silent empty database. Double-check the name.
One D1 database and one R2 bucket per app: a second `d1_databases` entry fails the deploy at validation ("Outer apps can have one D1 database and one R2 bucket for now; merge the extra ones"). The built `dist/wrangler.json` carries the binding to Cello, which creates the database on first use. Cello keys the database by name, so a typo opens a silent empty database. Double-check the name.

## Ship schema as migrations

Expand All @@ -29,7 +29,7 @@ Migration order depends on deploy state:
| App with a live version | Migrations run before the upload; the old code keeps serving, and a migrate failure uploads nothing |
| First deploy | Upload first, then migrate; the proxy returns 503 (building page) until the first deploy succeeds, so no race is possible |

Files apply in numeric-prefix order under the app's scoped storage credentials. Already-applied files are skipped, never re-applied. A file edited after it was applied fails the deploy. Write a new migration instead. A failing migration fails the deploy and names the file; the previous version keeps serving (first deploys stay not-live, "Your app isn't live yet"), with celld's error in the log tail. The step runs only when the built config declares `d1_databases` and the repo holds migration files; no files means the step is skipped.
Files apply in numeric-prefix order under the app's scoped storage credentials. Already-applied files are skipped, never re-applied. A file edited after it was applied fails the deploy. Write a new migration instead. A failing migration fails the deploy and names the file; the previous version keeps serving (first deploys stay not-live, "Your app isn't live yet"), with Cello's error in the log tail. The step runs only when the built config declares `d1_databases` and the repo holds migration files; no files means the step is skipped.

Expand first, contract later: the migration runs while the old code still serves, so prefer additive changes (new tables, nullable columns). Dropping a column the live code still reads serves errors until the new version takes over.

Expand Down
6 changes: 3 additions & 3 deletions web/docs/agents/backend/files.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,19 @@ title: Store uploads in R2
description: R2 uploads behind your own checks, the Console R2 browser, and the read-only Durable Object handler.
---

Extra state arrives as bindings in `void.config.ts`, validated from the built `dist/wrangler.json` at deploy time. Only keys celld accepts pass. One D1 database and one R2 bucket per app: a second `r2_buckets` entry fails the deploy at validation. The person-facing guide is [Store uploaded files](/backend/files-storage).
Extra state arrives as bindings in `void.config.ts`, validated from the built `dist/wrangler.json` at deploy time. Only keys Cello accepts pass. One D1 database and one R2 bucket per app: a second `r2_buckets` entry fails the deploy at validation. The person-facing guide is [Store uploaded files](/backend/files-storage).

## Gate uploads yourself

Declare file storage with `r2_buckets`. Uploaded images and video are not profanity-classified. Keep uploads behind your own checks, and never serve user uploads as executable content.

## Browse files in Console

Console → your app → **Data → R2** opens the app's single `r2_buckets` binding directly. You can browse folders, preview text (up to 256 KiB) and images inline, download (up to 64 MiB), upload (up to 64 MiB), create folders, and delete with confirmation. Reads use the same scoped credentials as your app; writes go through celld and are recorded in the agent action log. The binding list comes from the deployed manifest in your bucket, not the local build directory.
Console → your app → **Data → R2** opens the app's single `r2_buckets` binding directly. You can browse folders, preview text (up to 256 KiB) and images inline, download (up to 64 MiB), upload (up to 64 MiB), create folders, and delete with confirmation. Reads use the same scoped credentials as your app; writes go through Cello and are recorded in the agent action log. The binding list comes from the deployed manifest in your bucket, not the local build directory.

## Expose Durable Object state read-only

Console → your app → **Data → Durable Objects** lists every `durable_objects` binding's instances (read-only; celld exposes no generic storage API for an instance). Selecting an instance shows what the app's own `?read=1` handler returns for it. Implement that read-only branch without side effects:
Console → your app → **Data → Durable Objects** lists every `durable_objects` binding's instances (read-only; Cello exposes no generic storage API for an instance). Selecting an instance shows what the app's own `?read=1` handler returns for it. Implement that read-only branch without side effects:

```js
if (new URL(request.url).searchParams.has("read")) {
Expand Down
2 changes: 1 addition & 1 deletion web/docs/agents/backend/kv.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ cloudflare: {
},
```

`kv_namespaces` is an accepted deploy key, so the namespace deploys on every account. Binding keys are validated at deploy time. See [Store uploaded files](/backend/files-storage). Celld creates the namespace on first use; a typo opens a silent empty namespace, so double-check the id.
`kv_namespaces` is an accepted deploy key, so the namespace deploys on every account. Binding keys are validated at deploy time. See [Store uploaded files](/backend/files-storage). Cello creates the namespace on first use; a typo opens a silent empty namespace, so double-check the id.

## Use it

Expand Down
2 changes: 1 addition & 1 deletion web/docs/agents/backend/sandboxes.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Code-execution sandboxes are not available on Outer — do not ship

## Know why it cannot run

Void sandboxes (`getSandbox(id)`, `sandbox.run/files/fetch`) are isolated Linux containers fronted by a Durable Object. They need Cloudflare Containers: a container runtime on every machine that can start the app's image. Outer runs each app as a celld worker fleet: plain processes under cgroup and network isolation, no Docker/Podman daemon on the app host. A sandbox has nowhere to start. The `containers` wrangler key passes Outer's deploy validation, so the failure would come at runtime, not at deploy. Do not ship sandbox code expecting the deploy gate to catch it.
Void sandboxes (`getSandbox(id)`, `sandbox.run/files/fetch`) are isolated Linux containers fronted by a Durable Object. They need Cloudflare Containers: a container runtime on every machine that can start the app's image. Outer runs each app as a Cello worker fleet: plain processes under cgroup and network isolation, no Docker/Podman daemon on the app host. A sandbox has nowhere to start. The `containers` wrangler key passes Outer's deploy validation, so the failure would come at runtime, not at deploy. Do not ship sandbox code expecting the deploy gate to catch it.

## Do this instead

Expand Down
Loading
Loading