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, and writes nothing until the last one.

The container running your agent is its box. A deployment is the record saying where that box is: the agent template it serves, its public address, and the secret that signs traffic to it. A template has one box, so registering a new one replaces whatever was there before.

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.

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 a 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 the template, that click lands on Register deployment. Once you register one, the same click opens Studio.

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.

Where the secret comes from

You do not have to invent one. On its first boot the container mints a signing secret and stores it in its own database, so every restart reuses it. It prints the secret in its log at warning level. Copy that value. The container prints it only on the boot that mints it, so take it from that first log.

You can also decide the value yourself: set HMAC_SECRET on the container and it wins over anything the box would mint. That is the route to take when your platform injects secrets from a vault.

Step three: you are connected

The record exists. Every installation of that agent template now runs against the address you registered, including installations other people made.

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 dev in 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.
  • Nothing started a clock. The registration lives until you delete 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.

What's next

BUILT WITH ❤️ FROM CANADA AND SPAIN