> ## Documentation Index
> Fetch the complete documentation index at: https://celesto.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic usage

> Day-to-day Celesto workflows — create sandboxes, run shell commands, check exit codes and output, and handle errors using the Python SDK.

This page covers the everyday operations you need to work with Celesto: creating a sandbox, running commands inside it, reading the output, and handling errors. If you have not installed Celesto yet, start with the [quickstart](https://celesto.ai/docs/celesto/quickstart).

## Quick start

The simplest way to use Celesto is the auto-configuration mode:

```python theme={null} theme={null}
from celesto import Celesto

with Celesto() as vm:
    result = vm.run("uname -r")
    print(result.stdout)
```

When you create a `Celesto()` with no arguments, it automatically:

* Generates SSH keys (stored in `~/.celesto/keys/`)
* Builds an Alpine Linux image with SSH pre-configured
* Creates a VM with sensible defaults (512MB RAM, 1 vCPU)
* Starts the VM when entering the context manager

## Creating a sandbox

You can create a sandbox with sensible defaults or customize the configuration.

> [tab] Auto-config (Recommended)
>
> ```python theme={null} theme={null}
> from celesto import Celesto
>
> # Minimal configuration
> with Celesto() as vm:
>     print(f"VM running at {vm.get_ip()}")
>
> # Custom memory and disk size
> with Celesto(memory=1024, disk_size=1024) as vm:
>     print(f"VM ID: {vm.vm_id}")
> ```

> [tab] Manual Configuration
>
> ```python theme={null} theme={null}
> from celesto import Celesto, VMConfig
> from celesto import ImageBuilder, SSH_BOOT_ARGS
>
> # Build custom image
> builder = ImageBuilder()
> kernel, rootfs = builder.build_alpine_ssh()
>
> # Create VM with explicit config
> config = VMConfig(
>     vm_id="my-vm",
>     vcpu_count=2,
>     memory=1024,
>     kernel_path=kernel,
>     rootfs_path=rootfs,
>     boot_args=SSH_BOOT_ARGS,
> )
>
> with Celesto(config) as vm:
>     result = vm.run("echo 'Hello from Celesto'")
>     print(result.output)
> ```

## Running commands

The `run()` method executes commands via SSH and returns a `CommandResult` object:

```python theme={null} theme={null}
from celesto import Celesto

with Celesto() as vm:
    # Basic command execution
    result = vm.run("ls -la /")
    print(result.stdout)  # Command output
    print(result.exit_code)  # Exit status (0 = success)
    print(result.ok)  # True if exit_code == 0

    # Commands with custom timeout
    result = vm.run("sleep 10", timeout=60)

    # Handle command failures
    result = vm.run("exit 1")
    if not result.ok:
        print(f"Command failed: {result.stderr}")
```

### Shell modes

Celesto supports two command execution modes:

```python theme={null} theme={null}
# Login shell mode (default) - runs through guest login shell
result = vm.run("echo $HOME", shell="login")

# Raw mode - executes command directly with no shell wrapping
result = vm.run("/bin/ls", shell="raw")
```

## VM properties

Access VM information through properties:

```python theme={null} theme={null}
with Celesto() as vm:
    print(vm.vm_id)        # VM identifier
    print(vm.status)       # Current state (VMState.RUNNING)
    print(vm.get_ip())     # Guest IP address
    print(vm.info)         # Full VMInfo object (cached)
    print(vm.data_dir)     # State directory path

    # Refresh cached info from state store
    vm.refresh()
    print(vm.info.status)
```

## Checking SSH capability

Not all VM images support command execution. You can check before running commands:

```python theme={null} theme={null}
with Celesto() as vm:
    if vm.can_run_commands():
        result = vm.run("whoami")
        print(result.output)
    else:
        print("This VM does not support SSH command execution")
```

> [!NOTE]
>
> Command execution requires the VM to be booted with `init=/init` in the boot arguments. All auto-configured VMs and images built with `ImageBuilder` include this by default.

## Getting SSH connection details

Retrieve SSH commands for manual connection:

```python theme={null} theme={null}
with Celesto() as vm:
    ssh_cmds = vm.ssh_commands()
    print(ssh_cmds["direct"])     # SSH to guest IP
    print(ssh_cmds["localhost"])  # SSH via localhost (if forwarded)
```

## Error handling

Celesto raises specific exceptions for different failure scenarios:

```python theme={null} theme={null}
from celesto import Celesto
from celesto.exceptions import (
    CelestoError,
    CommandExecutionUnavailableError,
    OperationTimeoutError,
)

try:
    with Celesto() as vm:
        result = vm.run("some-command", timeout=5)
except CommandExecutionUnavailableError as e:
    print(f"SSH not available: {e.reason}")
    print(f"Remediation: {e.remediation}")
except OperationTimeoutError as e:
    print(f"Operation timed out: {e.message}")
except CelestoError as e:
    print(f"Celesto error: {e}")
```

## Next steps

> [card] [VM lifecycle](https://celesto.ai/docs/celesto/guides/vm-lifecycle.md)
>
> Learn about starting, stopping, and managing VM lifecycles

> [card] [Port forwarding](https://celesto.ai/docs/celesto/features/port-forwarding.md)
>
> Expose guest services to your host machine

> [card] [Environment variables](https://celesto.ai/docs/celesto/guides/environment-variables.md)
>
> Inject configuration into your VMs

> [card] [Custom images](https://celesto.ai/docs/celesto/guides/custom-images.md)
>
> Build custom rootfs images for your use case


## Related topics

- [Install Celesto on Linux or macOS](https://celesto.ai/docs/celesto/installation.md)
- [Caching](https://celesto.ai/docs/ci/caching.md)
- [Performance benchmarks](https://celesto.ai/docs/celesto/advanced/performance.md)
- [celesto doctor](https://celesto.ai/docs/celesto/cli/doctor.md)
- [Celesto: secure microVM sandboxes for AI agents](https://celesto.ai/docs/celesto/introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.