Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
Agent API key
Lets an AI agent that PortOS did not spawn — a Claude Code or Codex session you run in a terminal on the PortOS machine — call the PortOS API without the instance password. Agents PortOS spawns already get PORTOS_API_TOKEN injected (server/services/agentApiAuth.js) and need nothing here.
Turning it on
Settings > Security > Agent API key > Turn on. The card appears once a login password is set; without a password the API needs no credential.
While on, the server keeps one session token (label agent-key) in ~/.portos/agent-key.json, with the file at mode 0600 and its directory at 0700:
{
"version": 1,
"url": "http://127.0.0.1:5553",
"token": "<session token>",
"sessionId": "<opaque id>",
"expiresAt": "<ISO time>",
"cli": "<repo-root>/scripts/portos-api.js",
"usage": "Send \"Authorization: Bearer <token>\" to url. ..."
}
url is the loopback origin for this install: the HTTP mirror on :5553 when HTTPS is on, else :5555. Set PORTOS_AGENT_KEY_FILE (for both the server and the CLI) to use another path, for example when two installs share one home directory.
The server re-mints the key a week before its 30-day session expires (checked at boot and daily), and right after a password change or log-out-everywhere drops every session. Rotate replaces it on demand. Turn off and revoke revokes the session and deletes the file.
Calling the API
node <repo-root>/scripts/portos-api.js whoami
node <repo-root>/scripts/portos-api.js task "Fix the flaky upload test" --app portos --priority HIGH
node <repo-root>/scripts/portos-api.js get /api/cos/tasks
node <repo-root>/scripts/portos-api.js post /api/image-gen/generate '{"prompt":"a lighthouse at dusk"}'
node <repo-root>/scripts/portos-api.js post /api/music-video/autonomous @brief.json
node <repo-root>/scripts/portos-api.js get /api/api-docs/catalog.json
npm run --silent api -- <args> from the repo root is the same command. Bodies can be inline JSON, @file, or - for stdin. A path without /api/ or /data/ gets /api prepended. Output is the response body; a non-2xx exits 1 with the body on stderr.
PORTOS_API_TOKEN and PORTOS_URL, when set, win over the key file, so the same command works inside a PortOS-spawned agent.
Requests wait up to 30 minutes for long-running AI routes, including reading the response body. Pass --timeout <seconds> to change that deadline, for example portos-api post /api/music-video/autonomous @brief.json --timeout 3600. A timeout closes the client connection and reports the elapsed limit; the server may still be working, so check the outcome before submitting the same operation again.
Plain curl works too:
curl -sS "$(jq -r .url ~/.portos/agent-key.json)/api/cos/tasks" \
-H "Authorization: Bearer $(jq -r .token ~/.portos/agent-key.json)"
Security model
- The key is a session token, never the password. It carries the same operator authority as a signed-in browser or a PortOS-spawned agent, and the request audit identity names it as the
agent-keysession. - Holding the token is the only thing that grants it. Requests are never trusted for arriving on loopback: Tailscale serve and the dev proxy both deliver remote traffic to
127.0.0.1. - Anything that can read a
0600file in the host user's home already runs as that user and could mint a session fromdata/auth-sessions.json, so the file widens no boundary. It lives outsidedata/so backups and peer sync never carry the plaintext token (auth-sessions.jsonstores hashes only). - The on/off flag lives under
secrets.agentKeyinsettings.json, out of reach of the generic settings GET/PUT.PUT /api/auth/agent-keyandPOST /api/auth/agent-key/rotateare on the host-control list (server/lib/hostControlRoutes.js).GET /api/auth/agent-keyreports state and never the token.
Outside-agent merge admission
An outside terminal agent uses POST /api/cos/merge-admission/external; it does
not create a CoS agent record or borrow another run's agentId. The existing
operator boundary applies: a verified session (including the agent key) when
password protection is on, or a genuine local connection when it is off.
Anonymous remote and scoped peer requests cannot acquire or release admission.
Create one secret for this run and retain it until release is confirmed:
export PORTOS_ADMISSION_SESSION="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
portos-api.js sends it as X-PortOS-Admission-Session only to the external
admission endpoint. Keep it out of logs, reviewer environments, PRs and shared
files. It separates concurrent terminal runs sharing the same agent-key
credential. The server stores only a hash bound to the verified credential
identity. A different credential or run secret cannot check or release the
handle, even if it knows the lease token. Rotating/revoking the credential
invalidates its authority; an interrupted holder remains reserved until the
five-minute maximum hold elapses. This is the same bounded coordination as CoS
leases, not a forge-side fence against a merge already in flight at expiry.
Before acquiring, finish all configured reviews, required CI for the exact PR
head, and this repository's combined-tree structural guards outside the
lease. Keep the checked head and base SHAs and the base branch name. The worktree-private
portos-review-status file must name that exact REVIEW_HEAD and the workflow's
REVIEW_STATUS=clean, or optional-inconclusive when all configured reviewers
are optional and unavailable. The latter records an attempted head, never a
clean reviewer verdict. The outside operator remains responsible for satisfying
its configured review policy; admission is coordination, not CI certification.
Write the acquisition request to a private JSON file (mode 0600). For example:
{
"action": "acquire",
"appId": "example-app",
"worktreePath": "/example/repository-worktree",
"prUrl": "https://github.com/example/repo/pull/7",
"headSha": "1111111111111111111111111111111111111111",
"baseBranch": "main",
"baseSha": "2222222222222222222222222222222222222222"
}
node <portos-root>/scripts/portos-api.js post /api/cos/merge-admission/external @admission-target.json
The app must already exist in the local app registry. The server verifies its
origin and the checkout's real Git common directory, separate linked checkout,
branch, identity, local review receipt, live same-repository open PR, head and
base branch/SHA. The base SHA is the live refs/heads/<baseBranch> commit,
not GitHub's historical PR baseRefOid. Acquire and check read that ref with
the PR's repository, base branch and head through the app's authorized forge
transport; a moved or missing ref withholds admission until guards are rerun.
An active/uncertain CoS owner, checkout lock, retirement fence, changed
proof or unreadable state withholds admission. Fork PRs and detached/primary
checkouts are outside this bounded flow. Repository keys are shared with CoS
parents and the pending-merge sweep, so all three contend on the same lease;
different repositories remain independent.
Only admitted: true grants a lease. Retain its opaque token privately. A
repeat acquire by the same credential and run secret for the unchanged target
returns the same token without extending its deadline. Check and release take
no caller-selected target:
{"action":"check","token":"<lease UUID>"}
{"action":"release","token":"<lease UUID>","outcome":"merged"}
Use the same CLI endpoint and secret for both. Inside admission, perform the
final live PR/required-check read and confirm both the recorded head and base;
check also revalidates the stored target. If either SHA changed, release with
resync, repeat the relevant validation outside the lease, then acquire again.
Merge with gh pr merge --match-head-commit <CI-verified-head> and the repository's
chosen merge method; never use --delete-branch, --admin or deferred auto-merge.
Read the remote PR back and require MERGED at the expected head. Release with
merged, or leave-open when no merge occurred, and require released: true
before any cleanup. Release remains available to the same owner after a merge
or checkout change. Use the supported checkout preservation/retirement service
for cleanup; admission itself never mutates a checkout or Git ref.
A timeout, failed persistence or uncertain response is not proof of release. Preserve the checkout/ref and handle, resolve the actual outcome, and report a blocker if it cannot be established. Do not edit the CoS state file, manufacture a running parent, or borrow another owner's token. After expiry, an old holder must reacquire and repeat final live checks; its old token cannot release a successor's lease.
FableLoom static export
The authenticated CLI supports read-only preflight, build, explicit job status/watch,
and protected binary download. Episode IDs retain their supplied package order.
Omitting episode IDs exports all episodes in story order. Draft media is refused
unless --allow-draft true is explicit; voice also requires --characters true.
Preflight reports graph, outline, production, media and approval findings before a
build. The build repeats validation and checks source bytes; preflight is not a
finished-package certification.
node scripts/portos-api.js fableloom-export preflight LOOM --episodes EP1,EP2 --player true --profile web-720p
node scripts/portos-api.js fableloom-export start LOOM --episodes EP1,EP2 --player true --profile web-720p
node scripts/portos-api.js fableloom-export status LOOM JOB
node scripts/portos-api.js fableloom-export watch LOOM JOB --timeout 1800
node scripts/portos-api.js fableloom-export download LOOM JOB --output story.zip
watch prints findings, progress and final size and exits nonzero for a failed or
cancelled job. Downloads use the same credential transport, write ZIP bytes to a
new file with private permissions and refuse overwriting an existing file. The
ZIP is a static managed artifact; these commands do not deploy or host PortOS.