v0.12.1

You can now create nested directories when running a command in a sandbox.

Before, this request gave an error because the data directory didn't exist:

POST /v1/exec

{
    "sandbox": "ash",
    "command": "run",
    "files": {
        "": "cat data/hello.txt",
        "data/hello.txt": "hello world!"
    }
}

Now this request creates the data directory before writing hello.txt, and the command works just fine:

{
    "id": "ash_run_86408aef",
    "ok": true,
    "duration": 542,
    "stdout": "hello world!",
    "stderr": ""
}

v0.12.0

Codapi is a lightweight sandbox server for interactive documentation and learning. This release lets you run a source file in a sandbox directly from your terminal:

Usage: ./codapi-cli exec <sandbox> <command> <filename>

For example:

./codapi-cli exec ash run hello.sh
Hello, world!

This is especially helpful when debugging new sandboxes.

v0.11.0

Codapi is a lightweight sandbox server for interactive documentation and learning. This release introduces a command line interface — codapi-cli. It makes managing sandboxes much easier:

Usage: ./codapi-cli <command> [args...]

commands:
  sandbox add     Add a new sandbox
  sandbox rm      Remove an existing sandbox
  sandbox ls      List all sandboxes

See the sandboxes repository for a complete list of supported sandboxes.

v0.10.0

New sandbox layout

Previously, Codapi had its stuff organized into three folders: "images", "boxes", and "commands":

├── configs
│   ├── config.json
│   ├── boxes
│   │   ├── bash.json
│   │   └── python.json
│   └── commands
│       ├── bash.json
│       └── python.json
└── images
    ├── bash
    │   └── Dockerfile
    └── python
        └── Dockerfile

Now each sandbox gets its own subfolder inside the "sandboxes" folder:

├── codapi.json
└── sandboxes
    ├── bash
    │   ├── Dockerfile
    │   ├── box.json
    │   └── commands.json
    └── python
        ├── Dockerfile
        ├── box.json
        └── commands.json

All sandbox-related files live in a single folder, making it easier to create, edit, and distribute sandboxes.

Also, the main configuration file (previously configs/config.json) is now called codapi.json and resides next to the codapi binary.

The old layout is still supported for backward compatibility, but will be removed in future releases.

0.9.0

Box per file

Previously, all boxes were defined in a single configs/boxes.json file. Now each box is defined in a separate file in the configs/boxes directory:

• alpine.json
• python.json
• sqlite.json
• etc.

The single boxes.json file is still supported for backward compatibility, but will be removed in future releases.

0.8.0

Same-container steps

It's now possible to spin up a container in the before step and use it in subsequent steps. If you do this, don't forget to stop the container in the after step.

The :name in the box property is replaced with the actual container name at runtime.

Here is an example from the Caddy sandbox:

{
    "exec": {
        "engine": "docker",
        "entry": "main.sh",
        "before": {
            "box": "caddy",
            "action": "run",
            "detach": true,
            "command": ["caddy", "run"]
        },
        "steps": [
            {
                "box": ":name",
                "action": "exec",
                "command": ["sh", "main.sh"]
            }
        ],
        "after": {
            "box": ":name",
            "action": "stop"
        }
    }
}

0.7.1

⚠️ This is a critical security update. If you host a public-facing Codapi instance, you should upgrade as soon as possible.

This release protects against directory traversal attacks when writing request files.

Special thanks to @shadowscatcher for reporting this issue.

0.7.0

Different versions of the same box

You can define multiple versions of the same box in boxes.json:

{
    "alpine": {
        "image": "codapi/alpine"
    },
    "alpine:3.18": {
        "image": "codapi/alpine:3.18"
    }
}

and pass the version in the request:

{
    "sandbox": "sh",
    "version": "3.18",
    "command": "run",
    "files": {
        "": "echo hello"
    }
}

The default version is latest. It is assumed in both boxes.json and requests unless explicitly stated otherwise.

Binary file support

You can pass binary files in the request using data-url encoding. For example, this request:

{
    "sandbox": "sh",
    "command": "run",
    "files": {
        "main.sh": "ls data.bin",
        "data.bin": "data:application/octet-stream;base64,MTIz"
    }
}

will create the file data.bin on the server with a binary content of 123.

Temporary directory permissions

To avoid "permission denied" errors when the host user UID does not match the container user UID (see #6), the temporary directory for the request is now created with 777 permissions.

0.6.0

Modular sandbox configs

⚠️ This is a breaking change.

Config files config.json and boxes.json moved to config folder.

Config file commands.json split into multiple files in the config/commands folder. Now there is a separate file for each sandbox — this makes adding new sandboxes and commands much easier.

0.5.0

This is the first public Codapi release. However, it has had several private releases before, and has been battle-tested on codapi.org. So I consider it ready for non-critical production use cases (assuming you install it on a separate machine — this is a must for security reasons).