# Understanding the Limitations of microsandbox: Built-in Bounds and Constraints Explained

> Explore microsandbox limitations including byte limits for names and hostnames, API entry caps, and snapshot descriptor sizes. Learn about built-in bounds for host protection.

- Repository: [Super Rad Company/microsandbox](https://github.com/superradcompany/microsandbox)
- Tags: deep-dive
- Published: 2026-08-20

---

**microsandbox enforces strict built-in limits on sandbox names (128 bytes), hostnames (64 bytes), API list requests (100 entries), snapshot descriptors (1 MiB), and other runtime parameters to ensure host protection and predictable behavior.**

The **limitations of microsandbox** are intentionally designed safeguards embedded throughout its core Rust crates and type libraries. These bounds prevent resource exhaustion, guarantee cross-platform compatibility, and provide clear failure modes when configurations exceed safe thresholds. This article examines each limit's purpose, where it resides in the source code, and how to work within its constraints.

## Sandbox Identity Limits

### Maximum Sandbox Name Length (128 UTF-8 Bytes)

Sandbox names serve as primary identifiers across the microsandbox ecosystem. To stay within filesystem, API, and UI constraints, names are capped at **128 UTF-8 bytes** and must start with an ASCII alphanumeric character. Permitted characters include alphanumerics, dots, hyphens, and underscores.

In [`packages/microsandbox-types/rust/lib/validation.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/microsandbox-types/rust/lib/validation.rs), the constant `MAX_SANDBOX_NAME_BYTES` and the `validate_sandbox_name` function enforce this:

```rust
// From microsandbox-types validation.rs
pub const MAX_SANDBOX_NAME_BYTES: usize = 128;

pub fn validate_sandbox_name(name: &str) -> Result<(), ValidationError> {
    if name.is_empty() {
        return Err(ValidationError::EmptySandboxName);
    }
    let bytes = name.as_bytes();
    if bytes.len() > MAX_SANDBOX_NAME_BYTES {
        return Err(ValidationError::SandboxNameTooLong { max: MAX_SANDBOX_NAME_BYTES });
    }
    // ASCII alphanumeric first character check...
    // Character whitelist validation...
}

```

Names exceeding this limit trigger a `ValidationError` at build time, preventing deployment failures downstream.

### Maximum Hostname Length (64 UTF-8 Bytes)

Guest hostnames face a stricter **64-byte UTF-8 limit**, aligning with DNS and network stack conventions. Empty hostnames are explicitly rejected. The same [`validation.rs`](https://github.com/superradcompany/microsandbox/blob/main/validation.rs) file defines `MAX_HOSTNAME_BYTES` and `validate_hostname`.

When a sandbox name exceeds 64 bytes, microsandbox automatically derives a deterministic hostname via `hostname_from_sandbox_name`—hashing the name and truncating to a valid UTF-8 boundary without breaking multi-byte characters:

```rust
// Automatic derivation for long names
let derived = hostname_from_sandbox_name("very_long_sandbox_name_exceeding_sixty_four_bytes_limit")?;
// Result: 64-byte deterministic hash-based hostname

```

## API and Runtime Limits

### Sandbox List Request Pagination (100 Entries Maximum)

API consumers cannot request unbounded lists. The SDK enforces a **maximum of 100 sandboxes per list request**, with a **default page size of 20**. This protects both client memory and server response times.

In [`sdk/rust/lib/sandbox/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/mod.rs):

```rust
pub const DEFAULT_SANDBOX_LIST_LIMIT: u32 = 20;
pub const MAX_SANDBOX_LIST_LIMIT: u32 = 100;

```

```rust
// ❌ Exceeds limit — returns error
let oversized = client.list_sandboxes().limit(200).send(); // Err(LimitExceeded)

// ✅ Valid request
let page = client.list_sandboxes().limit(50).offset(0).send()?;

```

### Resource Limit (rlimit) Validation

While microsandbox doesn't impose hard caps above the host kernel's own limits, the `Rlimit` configuration API in [`sdk/rust/lib/sandbox/exec.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/exec.rs) validates proper structure and numeric values through `validate_rlimits`:

```rust
use microsandbox::sandbox::{SandboxBuilder, RlimitResource, Rlimit};

let sb = SandboxBuilder::new()
    .name("compute-heavy")
    .rlimit(RlimitResource::NOFILE, Rlimit::new(1024, 4096)?) // soft, hard
    .rlimit(RlimitResource::NPROC, Rlimit::new(64, 128)?)
    .build()?;

```

Invalid rlimit configurations—such as soft limits exceeding hard limits—are caught at build time rather than failing obscurely at runtime.

## Storage and Snapshot Constraints

### Snapshot Descriptor Size and Depth Limits

The snapshot subsystem implements multiple protective bounds defined in [`sdk/rust/lib/snapshot/migration.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/snapshot/migration.rs) and [`downgrade.rs`](https://github.com/superradcompany/microsandbox/blob/main/downgrade.rs):

| Limit | Value | Purpose |
|-------|-------|---------|
| Legacy descriptor size | ≤ 1 MiB | Backward compatibility |
| Current descriptor size | ≤ 1 MiB | Prevent memory pressure |
| Parent depth | ≤ 128 | Avoid unbounded ancestry chains |
| Inventory metadata | ≤ 4 MiB | Cap snapshot index overhead |

```rust
pub const MAX_LEGACY_DESCRIPTOR_BYTES: usize = 1 * 1024 * 1024;
pub const MAX_DESCRIPTOR_BYTES: usize = 1 * 1024 * 1024;
pub const MAX_PARENT_DEPTH: u32 = 128;
pub const MAX_INVENTORY_METADATA_BYTES: usize = 4 * 1024 * 1024;

```

Deep snapshot chains exceeding 128 parents trigger `MaxParentDepthExceeded`, forcing architectural decisions about flattening or archiving historical snapshots.

## Security and I/O Bounds

### Secret Placeholder Size (1024 Bytes)

Secrets embedded in sandbox specifications—such as injected credentials or API keys—are limited to **1024 bytes** as defined in [`packages/microsandbox-types/rust/lib/domain.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/microsandbox-types/rust/lib/domain.rs):

```rust
pub const MAX_SECRET_PLACEHOLDER_BYTES: usize = 1024;

```

This prevents accidental or malicious embedding of large data blobs where secrets belong, steering users toward proper secret management systems for larger payloads.

### Network Connection Limits

The networking crate defaults to **256 concurrent connections per listener**, with multi-tenant mode respecting the same cap. Found in [`crates/network/lib/tcp/connection.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/network/lib/tcp/connection.rs):

```rust
pub const DEFAULT_MAX_CONNECTIONS: usize = 256;

```

Load balancers or connection pools must be configured external to microsandbox for higher throughput scenarios.

### Console Write Buffer Size (4096 Units / ~8 KB)

To maintain compatibility with Windows console constraints, the terminal emulator limits individual writes to **4096 units** (approximately 8 KB). The `MAX_CONSOLE_WRITE_UNITS` constant in [`sdk/rust/lib/sandbox/terminal/encoding.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/terminal/encoding.rs) ensures cross-platform terminal stability:

```rust
pub const MAX_CONSOLE_WRITE_UNITS: usize = 4096;

```

Applications with verbose logging must implement their own buffering or pagination rather than relying on unbounded single writes.

## Practical Validation Examples

### Rust SDK

```rust
use microsandbox::sandbox::{SandboxBuilder, RlimitResource};

fn main() -> microsandbox::Result<()> {
    // ✅ Valid: name within 128 bytes, hostname auto-derived
    let sb = SandboxBuilder::new()
        .name("api-server-v2.3")
        .build()?;

    // ❌ Name exceeds limit
    let long_name = "x".repeat(129);
    assert!(SandboxBuilder::new().name(&long_name).build().is_err());

    // ❌ Explicit hostname too long
    let bad_host = "y".repeat(65);
    assert!(SandboxBuilder::new().hostname(&bad_host).build().is_err());

    Ok(())
}

```

### Python SDK

```python
import microsandbox

# Valid creation

sb = microsandbox.SandboxBuilder().name("worker-pool").build()

# Caught at build time

try:
    microsandbox.SandboxBuilder().name("x" * 129).build()
except microsandbox.ValidationError as e:
    print(f"Name too long: {e}")

# Hostname validation

try:
    microsandbox.SandboxBuilder().hostname("y" * 65).build()
except microsandbox.ValidationError as e:
    print(f"Hostname exceeds 64 bytes: {e}")

```

## Summary

- **Identity limits**: Sandbox names ≤ 128 bytes, hostnames ≤ 64 bytes with automatic derivation for long names.
- **API boundaries**: List requests capped at 100 entries, resource limits validated but kernel-bounded.
- **Storage protections**: Snapshot descriptors ≤ 1 MiB, parent depth ≤ 128, inventory metadata ≤ 4 MiB.
- **Security constraints**: Secrets ≤ 1024 bytes, enforced at specification time.
- **Runtime bounds**: 256 network connections per listener, 8 KB console write buffers for cross-platform safety.

## Frequently Asked Questions

### What happens if I exceed the sandbox name length limit?

The `validate_sandbox_name` function in [`packages/microsandbox-types/rust/lib/validation.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/microsandbox-types/rust/lib/validation.rs) returns a `ValidationError::SandboxNameTooLong` immediately when calling `SandboxBuilder::build()`. The error includes the maximum permitted value (128), allowing programmatic handling. No partial sandbox creation occurs.

### Can I increase the 100-entry limit for sandbox list requests?

No. `MAX_SANDBOX_LIST_LIMIT` is a compile-time constant in [`sdk/rust/lib/sandbox/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/mod.rs) without runtime configuration. Implement pagination using the `offset` parameter to retrieve larger result sets across multiple API calls.

### Are rlimit values hard-capped by microsandbox or the host?

Microsandbox validates `Rlimit` structure and logical consistency (soft ≤ hard) but defers to the host kernel's maximum values. Attempting to set limits beyond kernel capability results in runtime errors from the underlying system, not from microsandbox's validation layer in [`sdk/rust/lib/sandbox/exec.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/exec.rs).