# Start and Ready Commands

<subtitle>Define background services started during template build and readiness check logic.</subtitle>

>
> **Prerequisites**: Please complete [API Key Configuration](/docs/agent-sandbox/product/01-prerequisites) first

## Start Command

Start Command is used to start background services that need to run persistently during **template build** and write their running state to snapshots.

Typical use cases include:
- Web servers (such as Node.js, Python Flask)
- Database services (such as SQLite, Redis)
- Background daemons

When you create sandboxes based on this template, these services will be in started and ready state. Users can use them immediately after connection without waiting for service initialization.

>
> For how it works, see: [How Templates Work](/docs/agent-sandbox/concepts/02-how-it-works)

## Ready Command

Ready Command is used to determine whether the **template sandbox** has reached an available state before creating [snapshots](/docs/agent-sandbox/concepts/02-how-it-works).

The system will repeatedly execute this command until it returns exit code **0**. This allows you to precisely control: before snapshot generation, how much you need to wait for the [Start Command](#start-command) to complete (or wait for which system conditions to be satisfied).

## Usage

Set commands to run when sandbox starts and commands to determine when sandbox is ready:

```python
from ucloud_sandbox import Template, wait_for_port, wait_for_timeout

template = Template().from_base_image()

# Set both start command and ready command
template.set_start_cmd("npm start", wait_for_port(3000))

# Set only ready command
template.set_ready_cmd(wait_for_timeout(10_000))
```

Ready commands are used to determine when the sandbox is ready to accept connections.

> You can only call these commands once per template. Subsequent calls will throw errors.

## Ready Command Helper Functions

SDK provides helper functions for common ready command patterns:

```python
from ucloud_sandbox import wait_for_port, wait_for_process, wait_for_file, wait_for_timeout

# Wait for port to be available
wait_for_port(3000)

# Wait for process to run
wait_for_process("node")

# Wait for file to exist
wait_for_file("/tmp/ready")

# Wait for specified time
wait_for_timeout(10_000)  # 10 seconds
```