---
title: 'Connect your box'
description: 'Point an agent at the container you run, from the browser: check the address, prove the secret, register. No terminal needed.'
position: 1
---

# 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`](/docs/cli/reference/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 Register deployment wizard, showing the box answering with its protocol version, Stackbone version and platform capabilities.](/images/deployments/box-answered.png)
_Step one, after the browser has called the box._

## What you need first

| You need                    | Why                                                                                                                                            |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| A running container         | Stackbone provisions nothing. [`stackbone package`](/docs/cli/reference/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](#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.

![An agent template page listing one active installation with an Open action.](/images/deployments/open-your-agent.png)

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**.

![Step one of the wizard with an empty box address field.](/images/deployments/step-address.png)

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](/docs/home/deployments/troubleshooting#the-box-is-too-old).                      |
| **Not a box** | Something replied, but not a handshake.          | [Check the address](/docs/home/deployments/troubleshooting#something-answered-but-it-is-not-a-box). |
| **No answer** | Nothing came back.                               | [Three things to check](/docs/home/deployments/troubleshooting#nothing-came-back).                  |

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**.

![Step two of the wizard, asking for the signing secret.](/images/deployments/step-secret.png)

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](/docs/home/deployments/troubleshooting#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](/docs/home/deployments/troubleshooting#the-box-was-not-told), 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 success panel, naming the registered address and the stackbone dev command.](/images/deployments/registered.png)

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`](/docs/cli/reference/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

- **[When registration fails](/docs/home/deployments/troubleshooting)**: every
  refusal the wizard can show, and the way out of each.
- **[`stackbone link`](/docs/cli/reference/link)**: the same
  registration from a terminal, useful in a deploy script.
- **[Local development](/docs/cli/guides/local-development)**: running the agent on
  your own machine instead, with no box to register.