CodeLand Runner

Introduction

CodeLand Runner is a lightweight HTTP server designed to execute code snippets and return the results. It is primarily used in conjunction with the CodeLand Manager project for managing code execution on remote runners.

The CodeLand Runner provides a simple HTTP interface for executing code snippets and retrieving the results in a structured JSON format. It can be easily integrated into various systems that require remote code execution capabilities.

This repository contains the CodeLand Runner code, which is a part of the CodeLand Manager ecosystem.

Usage

To use the CodeLand Runner, you'll typically follow these steps:

1. Compile the Code: Compile the CodeLand Runner code using the provided build script or your preferred method. Ensure that all dependencies, including the cJSON library, are correctly set up.

2. Run the Server: Start the CodeLand Runner server on the desired host and port. By default, it listens on port 15000, but you can customize it by setting the runnerPort environment variable.

3. Send Requests: Use HTTP requests to send code snippets to the CodeLand Runner for execution. You can send POST requests with a JSON payload containing the code to be executed. The runner will execute the code and return the results.

4. Receive Results: Parse the JSON response from the CodeLand Runner to retrieve the execution results. The response includes a "res" field containing the base64-encoded output of the executed code.

Example

Here's an example of sending a POST request to execute code with the CodeLand Runner using curl:

curl -X POST http://localhost:15000 -d '{"code": "echo \"Hello, CodeLand!\"" }'

The response will be a JSON object with the execution result:

{
  "res": "SGVsbG8sIENvZGVMYW5kIQo="
}

Running as a macOS service

On macOS, the runner can be installed as a boot-time LaunchDaemon — a system service that starts at boot, runs as root, and restarts automatically if it crashes.

Files

File	Purpose
crunner.plist	LaunchDaemon definition (com.codeland.crunner): start at boot, keep alive, log to /var/log/crunner.log
install_service.sh	Builds the binary, installs it to /usr/local/bin/crunner, installs the plist to /Library/LaunchDaemons/, and loads the service
uninstall_service.sh	Stops the service and removes the binary and plist

Install

./install_service.sh

The script requires sudo. After it finishes, the runner is listening on port 15000 (or the runnerPort value set in the plist).

Verify it is running

launchctl print system/com.codeland.crunner   # service status (look for state = running)
curl -X POST http://localhost:15000 -d '{"code": "echo ok" }'
tail -f /var/log/crunner.log                  # logs

A healthy response looks like:

{"res":"b2sK"}

(b2sK is ok\n base64-encoded.)

Manage

sudo launchctl bootout system/com.codeland.crunner    # stop (service stays installed)
sudo launchctl kickstart -k system/com.codeland.crunner  # restart / reload config
./uninstall_service.sh                                 # remove the service entirely

To change the port, edit the runnerPort value in crunner.plist (and in /Library/LaunchDaemons/com.codeland.crunner.plist if already installed), then reload with sudo launchctl kickstart -k system/com.codeland.crunner.

Troubleshooting

• plutil -lint crunner.plist validates the plist syntax.
• If the service is stuck in spawn scheduled / exited state, check /var/log/crunner.log — the most common cause is another process already bound to the port.
• launchctl print system/com.codeland.crunner prints Bad request. when the service is not currently loaded.

Security note

Because the daemon runs as root, any code sent to the runner executes with root privileges. Keep the port closed to untrusted networks if the machine is exposed.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

• William Mantly (wmantly@gmail.com)

---

This README was generated with ❤️ by an AI language model.