Skip to main content
Custom sandboxes are provider integrations developed outside Harbor’s built-in registry. They may be local work in progress or private integrations not intended for upstream. Implement BaseEnvironment to add one.

Run a custom sandbox

Custom sandboxes are not registered by name, so pass module.path:ClassName to --env (-e). Harbor imports the custom sandbox on the host. Install its module and provider SDK in the same Python environment as Harbor. For a MySandbox class in my_sandbox.py, use my_sandbox:MySandbox.
Pass constructor options with --environment-kwarg (--ek) or environment.kwargs:

Declare sandbox options

Set options_model to an EnvironmentOptions subclass to validate your sandbox’s --ek values. Add the declaration to your existing sandbox implementation:
my_sandbox.py
BaseEnvironment.__init__() binds runtime inputs, validates the remaining user kwargs, and stores the parsed model in self.options. If your sandbox needs constructor logic, forward the arguments to the base before reading options:
No constructor override is needed if you only read options in lifecycle methods. If base validation depends on provider state that must be initialized earlier, declare runtime inputs explicitly and parse the remaining provider kwargs before calling super().__init__(). The base preserves already-parsed options. Harbor validates declared options before queueing trials and rejects unknown keys. Keep injected runtime inputs, such as paths, loggers, and task configuration, outside your options model. Custom environments without an options_model keep their existing kwargs behavior. Preflight overrides receive user-facing kwargs. Accept the argument and call super().preflight(kwargs) before checking provider credentials:
No-argument preflight(cls) overrides must be updated to this signature. List built-in environments without starting a sandbox:

Implement a custom sandbox

Extend BaseEnvironment and implement its lifecycle, command execution, and file-transfer methods. Harbor rejects custom classes that do not inherit from BaseEnvironment. Use _validate_definition() to reject tasks missing required files, such as environment/Dockerfile. If no task files are required, it can be empty.
my_sandbox.py
_merge_env() applies sandbox, agent-phase, and verifier-phase variables. _resolve_user() applies Harbor’s default execution user. Use both in every exec() implementation. Declare only capabilities the provider enforces. If docker_compose is enabled, also implement the per-service execution and file-transfer methods used by Compose tasks.
Add preflight() to check provider credentials before trials are queued. Keep provider credentials in the Harbor process; see Environment variables.