Agent ready

Why the agent is not ready instantly#

When you start a SpineOS desktop, the AI agent does not become available the moment the VM powers on. Several boot phases need to complete first. Knowing the sequence helps you understand why chat may not work immediately.

Boot phases#

A new desktop is usually working, its agent included, about 2 minutes after you create it. The phases below run in this order, and the agent's own start is the longest of them.

Phase 1: VM boot#

The virtual machine powers on, loads the OS, and starts core services. By the end of this phase, the VM has an IP address and basic network connectivity.

What works: VNC viewer shows the boot screen.

What does not work yet: terminal, chat, file transfers.

Phase 2: System initialization#

The initialization process runs the desktop's setup scripts:

• Configures the agent user
• Writes the agent configuration
• Installs enabled plugins
• Sets up the workspace (soul file, agents file, memory directory)
• Starts background services (terminal server, AI agent)

What works: VNC viewer shows the desktop loading. Terminal becomes available toward the end.

What does not work yet: chat, because the AI agent is still starting.

Phase 3: Agent startup#

The AI agent starts, loads its configuration, and begins accepting connections. SpineOS checks the agent to confirm it is ready.

What works: everything. VNC, terminal, file transfers, and chat.

agentReady = true#

The desktop is marked agentReady only after SpineOS confirms that the AI agent is running and accepting connections. This means the agent is fully initialized and ready to accept messages.

In the dashboard, the chat panel becomes active when agentReady is true.

Why chat fails before agentReady#

Until the agent is ready, the chat panel's header and its message box say "Agent starting up...", and the message box does not accept messages. Through the API, a message sent before then is refused with a 503 error. This is by design: a message sent to an agent that has not started would either fail silently or produce confusing errors.

Typical boot timeline#

The total varies with the agent, how many plugins are enabled, and the current infrastructure load.

Checking agent status#

Each desktop card on the dashboard says "Booting" while the agent starts, then "Running". It says "Action required" instead when the desktop needs you, for example to sign in to Grok. On the desktop's page, the toolbar shows the boot's progress until then, and the chat panel's message box opens once the agent is ready.

What if the agent never becomes ready?#

A new desktop's agent is usually ready about 2 minutes after creation. At the 3-minute mark the toolbar may show "Boot is taking longer than expected." That message alone is not a reason to restart. If the agent is still not ready 4 minutes after creation, go through these steps before you restart the desktop:

1. If a card in the chat panel says the agent did not start, do what Agent not responding says for that card.
2. Otherwise, check the account or API key your desktop runs on, with your provider.
3. Stop the desktop, wait for it to show "Stopped", then start it again.

A Grok desktop is the exception: it waits for you to sign in with your xAI account, and its chat shows a "Sign in to Grok" card. Sign in there and do not restart: a restart brings the same card back.

If the issue continues, see the troubleshooting guide or contact support at contact@spinestudio.dev.