Deploy an agent from GitHub

There are two ways in. The B3OS Deploy app deploys a repository's b3os.yaml on each push, with no workflow file and no key in the repository. Or a GitHub Actions workflow runs b3os apply with a project key, as the template below does.

With the B3OS Deploy app

B3OS renews the live deploy's services itself, so no schedule runs in the repository. Redeploy and roll back from the application in the console.

With a GitHub Actions workflow

The template is a whole repository for a research agent. Its harness, a small TypeScript service, runs in a sandbox on the B3OS node and calls the model served there, vision and a pack through the sandbox's grant, with no API key inside the sandbox. The Python the model writes runs in a second sandbox made for each question, which holds no credential and has no network (head and hands). A file in the repository, b3os.yaml, declares all of it. A GitHub Actions workflow runs b3os apply on every push to main, and b3os apply --keepalive on a schedule, which keeps the harness running.

The template is not yet published as a public repository. Its own README.md shows the plan and the deploy output, recorded against the test double.

What the agent does

You add a question to a table in your Postgres database. The harness claims it, and the agent reads pages with vision, runs a routine that reads several pages at once, lists a page's links with a program that ships in the repository, works things out in Python it writes, and answers with the node's model. When the question names a GitHub repository, the harness files the answer there as an issue through the GitHub pack.

The harness's sandbox gets only the scopes these entries imply. Its egress allows the database's host and port and nothing else on the internet: the model, vision, the routine and the pack are reached through B3OS. The hands get no B3OS access and egress deny. A host that is not in the allowlist does not resolve either: with no hosts at all, nothing outside B3OS resolves, not even in DNS (egress with no hosts).

Before you start

• A project key with routines:read, routines:write, routines:run, sandboxes:read, sandboxes:write, sandboxes:run, vault:read, vault:run, actions:read, actions:run, infer:read, infer:run and vision:run. Give it a spend cap and an expiry (keys).

• A Postgres database the internet can reach.

• Two connections in the same project. The repository never holds a credential; it names these by label:

  bash
  printf %s "$DATABASE_URL" | b3os connect new --type bearer --label research-dbb3os connect io.b3os/github --label github-bot

  The vault has no URL field, so the postgres:// URL is stored as a bearer connection's token. A connection with no hosts is never added to any request; it reaches the harness only as the sandbox secret b3os.yaml names.

Deploy it

Check the plan before you push

From a clone, with the key in B3OS_API_KEY:

bash
b3os manifest validate     # offline: the file, its schema and its referencesb3os apply --dry-run       # reads the project; changes nothing

The dry run, like the deploy, uses what is committed: commit b3os.yaml and the routine file first. Its marks are those of the plan.

How the harness stays up

Each deploy starts a new generation: a sandbox restored from the build snapshot, given the source and the environment, and started. The build is reused until package.json or package-lock.json changes. A generation is a sandbox with a timeout of at most 3,600 seconds (sandbox limits), and every keepalive renews it. When the workflow stops running, the harness stops within that timeout.

When a new generation is ready, the old one gets SIGTERM. The template's harness then stops the agent, puts its question back in the queue, closes the database and exits. Its GET /healthz answers 200 only while its work loop is moving, and each keepalive runs that probe, so a harness whose loop is stuck gets a new generation.

To roll back, run the workflow by hand with ref set to an older commit. From a clone, b3os app rollback does the same without a checkout: it deploys the commit of the previous deploy that went live (or of --to dep_...), says in its plan and its deploy that it is a rollback, and leaves your working tree and HEAD as they are; a commit the clone lacks is an error that names the fetch to run. Keepalive recreates a lost harness from the commit it ran, never from the newest one on main, so it does not undo a rollback, and it says so: running caebec0 by rollback; HEAD is ee70e90. The next b3os apply deploys HEAD again.

What the template leaves out

• An address. The harness takes its work from the database; it gets no stable URL in this design. A service you give a public port is served at its preview URL under a path prefix (/sbx/.../), so absolute asset paths 404 and cookies are not kept; the plan says so in one line under the service, with a link to ports.
• Previews. Pull requests do not deploy.
• More than one copy. One generation serves at a time, apart from the overlap during a cutover.