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

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, the constant MAX_SANDBOX_NAME_BYTES and the validate_sandbox_name function enforce this:

// 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 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:

// 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:

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

// ❌ 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 validates proper structure and numeric values through validate_rlimits:

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 and 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

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:

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:

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 ensures cross-platform terminal stability:

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

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

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}