Connect your box
You run your agent's container in your own cloud, then tell Stackbone where it lives. This page does that from the browser in three steps. The wizard writes nothing until you submit the second one.
The container running your agent is its box. A deployment is the record saying where that box is: the installation it serves, its public address, and the secret that signs traffic to it. An installation has one box, so registering a new one for the same installation replaces whatever was there before. A box answers for exactly one installation: install the same template twice and you run two boxes, each registered from its own installation.
You can write that record two ways, and both produce the same row.
stackbone link does it from a terminal.
The wizard on this page does it from a browser, which lets a teammate connect a
box without installing anything.
The box comes from stackbone package, which packages the agent alone by
default. This page registers that folder. --target self-host writes a
different folder, with a dashboard of its own inside it, and the wizard on this
page has nothing to do with it: see
Self-host behind a proxy. The proxy rules on
that page do apply here (response buffering off, a long read timeout, a request
body limit of at least 26 MB), because both folders ship the same agent container
and the browser reaches it through your proxy either way.
Step one, after the browser has called the box.
What you need first
| You need | Why |
|---|---|
| A running container | Stackbone provisions nothing. stackbone package writes the folder you bring up with Docker. |
An https:// address |
Your browser calls the box itself, so the address needs TLS. The form refuses plain http:// before sending anything. |
| The box's signing secret | You prove it in step two. See Where the secret comes from below. |
| Permission to manage agents | Your role in the organization that owns the agent template has to allow it. Without it you never see the wizard, and the API refuses to write. |
| A recent image | The box has to speak agent protocol version 15 or later. Step one catches an older one. |
The address does not have to be reachable from the internet. Your browser makes the call, so a box that only answers inside your own network works as long as the machine you are sitting at can reach it.
Open the agent
Go to Workspaces, open the workspace that holds your agent, and click Open on its installation.
With no box on that installation, that click lands on Register deployment. Once you register one, the same click opens Studio. The wizard registers the installation you opened it from, so open it from the installation the box is meant to serve.
Step one: give it the address
Type the address the box answers on and click Call the box.
The form checks the address is https:// before anything leaves the page. Then
your browser calls the box's handshake, which needs no credentials, and reports
what answered:
| Verdict | What it means | What to do |
|---|---|---|
| Answered | A Stackbone box, recent enough to register. | Continue. |
| Too old | A box on an image from before this flow existed. | Update the image. |
| Not a box | Something replied, but not a handshake. | Check the address. |
| No answer | Nothing came back. | Three things to check. |
On success the panel shows the protocol version the box speaks, the Stackbone version inside it, and the platform capabilities it offers. Read that panel to confirm which box you reached before you hand over a secret.
The wizard has saved nothing yet. Close the tab here and you leave no half-finished record behind.
Step two: prove the secret
Type the box's signing secret and click Prove and register.
Your browser signs a challenge with the secret and the box says whether it can reproduce that signature from the one it holds. Stackbone receives a secret the box has already confirmed, so a wrong one writes nothing. If the box refuses it, see the secret was not accepted: a drifted clock looks like a wrong secret, and the page covers both.
Between the proof and the write, the wizard tells the box which installation it answers for. A box that cannot record that shows its own refusal, and the wizard registers nothing.
Past that point the wizard has told the box. If Stackbone then refuses the write, the box keeps answering for this installation with no record to match it: the box was not registered covers what to do.
Where the secret comes from
Read it off the .env in the folder
stackbone package wrote. That folder mints
HMAC_SECRET when it is generated, and the value after the = is what this
step asks for. Copying a trailing space counts as a different secret, so copy
that value alone.
A container started with no HMAC_SECRET mints one on its first boot and stores
it in its own database, so every restart reuses it. It prints that value in the
log once, framed in a banner at warning level, on the boot that minted it. Take
it from that log. Anyone who can read those logs can read it too.
You can also decide the value yourself: set HMAC_SECRET on the container and
it wins over anything the box would mint, and the box prints nothing. Take that
route when your platform injects secrets from a vault.
Step three: you are connected
The record exists. The installation you opened the wizard from now runs against the address you registered. Other installations of the same template are untouched: each one needs a box of its own, registered from that installation.
Two things did not happen:
- The folder on your computer is still unlinked. A page in a browser cannot
write files on your machine. Run
stackbone devin that folder. It asks which agent it is, then writes the answer down, so you never type the address and the secret a second time. - No clock started. The registration lives until you delete its installation, its agent template or its organization. No job sweeps a box that has been quiet.
Click Open Studio to reach the agent, or reopen the installation from Workspaces, which now goes straight to Studio.
After an upgrade: register every box once
Deployment records used to belong to the agent template. They now belong to the
installation, because a box answers for one installation id and refuses every
other. When your control plane picked up that change, it attached each existing
record to the oldest cloud installation of its template and reset it: status
pending, no address, no secret. Records whose template had no cloud
installation were removed.
So after that upgrade, register every box once more, either from this wizard or
with stackbone link --installation <id>. Until you
do, opening the installation lands on Register deployment again. A
stackbone dev session is not affected: a local-dev installation reaches its
runtime through the dev tunnel and never through this record.
When Studio refuses the box
Studio reaches the box directly, and the box checks which installation the request is for. Two refusals name the registration rather than your session:
| Studio says | What happened | What to do |
|---|---|---|
| This box answers for a different installation | The box was registered for another installation, so it refuses this one. Signing in again changes nothing. | Register the box for this installation: open the wizard from it, or run stackbone link --installation <id>. |
| This box has not been registered | The box is reachable but was never told which installation it answers for, so it refuses every call. This is the state before registration. | Register it: open the wizard from the installation, or run stackbone link --installation <id>. |
Any other refusal with a 401 is about your session, and signing in again is the remedy.
What's next
- When registration fails: every refusal the wizard can show, and the way out of each.
stackbone link: the same registration from a terminal, useful in a deploy script.- Local development: running the agent on your own machine instead, with no box to register.