Skip to content

bug(gateway): 0.0.96 rejects sandbox names >19 chars, breaking the OpenClaw integration #2651

Closed

Description

@rocket-turkey

Summary

OpenShell 0.0.96 enforces a hard 19-character maximum on sandbox names. The gateway rejects any longer name with gRPC INVALID_ARGUMENT. This makes 0.0.96 unusable with the official OpenClaw integration, whose sandbox names are structurally ≥24 characters and cannot be shortened through configuration.

Environment

  • OpenShell gateway 0.0.96 (release v0.0.96)
  • Docker compute driver, Linux x86_64
  • OpenClaw agent runtime via the openshell plugin

Reproduction

CreateSandbox (or openshell sandbox create --name <name>) with a name longer than 19 characters is rejected:

$ openshell sandbox create --name openclaw-agent-dev-abcf4511 --from openclaw -- echo hi
Error:   × code: 'Client specified an invalid argument',
  message: "name exceeds maximum length (27 > 19)"

A name of exactly 19 characters works:

$ openshell sandbox create --name openclaw-agent-dev1 --from openclaw -- echo hi
Created sandbox: openclaw-agent-dev1

Why this breaks the OpenClaw integration

The OpenClaw integration names each agent's sandbox openclaw-agent-<agentId>-<8-hex-hash>. The fixed prefix openclaw-agent- is 15 characters, plus a hyphen and an 8-character hash — so every generated name is ≥24 characters before the agent id, and can never fit within 19.

There is no configuration lever to reconcile this: no sandbox-name/prefix/length key in the openshell plugin config, none in the per-agent sandbox config, and no gateway-side limit override. The gateway therefore rejects CreateSandbox for every OpenClaw agent, and no sandbox can be created at all.

Regression

The same integration and the same ≥24-character names worked on 0.0.85; the 19-character limit appears to be introduced in a later 0.0.9x release. Downgrading is not a clean workaround because 0.0.96 migrates the gateway state DB forward, and an older gateway then refuses to start against the migrated schema (migration N was previously applied but is missing in the resolved migrations).

Ask

One of:

  • Raise or remove the 19-character sandbox-name limit, or make it configurable; and/or
  • Document the limit and coordinate with the OpenClaw integration so its generated names fit (shorter prefix, shorter hash, or a configurable name).

If 19 is a hard downstream constraint (a Docker/Kubernetes/DNS-label budget), it would help to state that in the error and in the docs, so integrations can generate names accordingly.

Activity

  1. krishicks commented on Aug 7, 2026

    @krishicks
    Contributor

    Triage by gpt-5.6-sol medium:

    The core claim in issue #2651 is correct: OpenShell enforces a gateway-wide 19-byte/character maximum on sandbox names.

    The limit is defined here:

    • crates/openshell-server/src/grpc/mod.rs:125
    • crates/openshell-server/src/grpc/validation.rs:167
    • crates/openshell-server/src/grpc/sandbox.rs:215

    The resulting error is exactly:

    name exceeds maximum length (<length> > 19)

    Why 19?

    It is a service-routing hostname budget, not a Docker constraint:

    {workspace}--{sandbox}--{service}.{base-domain}

    The first hostname label must be at most 63 characters. The implementation assigns every component an equal worst-case budget:

    19 + 2 + 19 + 2 + 19 = 61

    Twenty characters each would produce 64. The rationale is documented immediately above the constant and implemented in crates/
    openshell-server/src/service_routing.rs:77. The -- separators also make the three components unambiguous to the hostname parser.

    git history identifies the introduction as:

    5952a5a feat(workspace): add workspace resource model with scoping, membershi… (#2243)

    That commit:

    • Added workspace-prefixed service hostnames.
    • Added MAX_ROUTABLE_NAME_LEN.
    • Changed sandbox validation from MAX_NAME_LEN—253 characters—to 19.
    • Explicitly shortened tests and examples “to comply with MAX_ROUTABLE_NAME_LEN.”
    • Landed after v0.0.87 and before v0.0.88, so the regression begins in v0.0.88, earlier than the issue suggests.

    The RFC confirms the architectural motivation: workspace scoping changed service URLs from two components to a consistently parseable two-or-three-component form. See rfc/0011-multi-player-design/README.md:1134.

    One important nuance: this is a conservative global restriction. Kubernetes only constructs {workspace}--{sandbox} and independently validates the combined name against 63 characters in crates/openshell-driver-kubernetes/src/driver.rs:1178. Docker and Podman do not require a 19-character limit. OpenShell imposes it at sandbox creation so every sandbox can later expose a maximally named service, even when service routing is unused or disabled.

    So the likely conclusion is: the limit was deliberately introduced for deterministic service-routing hostnames, but applying a fixed equal-share budget to all sandbox names is unnecessarily restrictive for many cases. The issue also correctly exposes a documentation gap: workspace CLI help mentions 19 characters, while sandbox creation help and published sandbox documentation do not.

    @derekwaynecarr Given you authored 5952a5a, can you take a look at this?

  2. added
    state:validatedFactual assessment complete; awaiting maintainer disposition
    and removed
    state:triage-neededOpened without agent diagnostics and needs triage
    on Aug 7, 2026
  3. sallyom commented on Aug 18, 2026

    @sallyom

    This was recently fixed in OpenClaw with PR #115058 (openclaw/openclaw#115058).

    It changed OpenShell sandbox names to exactly 19 characters: oc- plus a 16-character hash.

    The next OpenClaw stable release will include the fix. Currently, fix is in Beta: 2026.8.1-beta.2

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:validatedFactual assessment complete; awaiting maintainer disposition

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions