unsandbox.com

Execute code immediately and wait for results. Best for quick scripts and interactive use.

Request Parameters

Example (Erlang)

#!/usr/bin/env escript
%%! -pa _build/default/lib/jsx/ebin

main(_Args) ->
    inets:start(),
    ssl:start(),

    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,

    Url = "https://api.unsandbox.com/execute",
    Headers = [
        {"Content-Type", "application/json"},
        {"Authorization", "Bearer " ++ ApiKey}
    ],
    Body = "{\"language\":\"python\",\"code\":\"print('Hello from unsandbox!')\"}",

    case httpc:request(post, {Url, Headers, "application/json", Body}, [], []) of
        {ok, {{_, 200, _}, _, Response}} ->
            Result = jsx:decode(list_to_binary(Response), [return_maps]),
            ExitCode = maps:get(<<"exit_code">>, Result, 1),
            case ExitCode of
                0 ->
                    io:format("Output: ~s~n", [maps:get(<<"stdout">>, Result)]);
                _ ->
                    io:format("Error: ~s~n", [maps:get(<<"stderr">>, Result)])
            end;
        {error, Reason} ->
            io:format("Request failed: ~p~n", [Reason])
    end.

Response (Success)

{
  "success": true,
  "stdout": "Hello from unsandbox!\n",
  "stderr": "",
  "exit_code": 0,
  "language": "python",
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "artifacts": [],
  "execution_mode": "pooled",
  "network_mode": "zerotrust",
  "total_time_ms": 523
}

Response (Error)

{
  "success": false,
  "stdout": "",
  "stderr": "SyntaxError: invalid syntax\n",
  "exit_code": 1,
  "language": "python",
  "job_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "artifacts": [],
  "execution_mode": "pooled",
  "network_mode": "zerotrust",
  "total_time_ms": 312
}

Submit code for execution and receive a job ID to poll for results. Best for long-running scripts or when you need to decouple submission from execution.

Request Parameters

Example (Erlang)

#!/usr/bin/env escript

main(_Args) ->
    inets:start(),
    ssl:start(),

    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,

    % Submit job
    Url = "https://api.unsandbox.com/execute/async",
    Headers = [
        {"Content-Type", "application/json"},
        {"Authorization", "Bearer " ++ ApiKey}
    ],
    Body = "{\"language\":\"rust\",\"code\":\"fn main() { println!(\\\"Computing...\\\"); }\",\"ttl\":300}",

    {ok, {{_, 200, _}, _, Response}} = httpc:request(post, {Url, Headers, "application/json", Body}, [], []),

    Job = jsx:decode(list_to_binary(Response), [return_maps]),
    JobId = maps:get(<<"job_id">>, Job),

    io:format("Job submitted: ~s~n", [JobId]),

    % Poll for results
    poll(JobId).

poll(JobId) ->
    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,
    Headers = [{"Authorization", "Bearer " ++ ApiKey}],
    StatusUrl = "https://api.unsandbox.com/jobs/" ++ binary_to_list(JobId),

    {ok, {{_, 200, _}, _, Response}} = httpc:request(get, {StatusUrl, Headers}, [], []),
    Status = jsx:decode(list_to_binary(Response), [return_maps]),

    case maps:get(<<"status">>, Status) of
        <<"completed">> ->
            ExitCode = maps:get(<<"exit_code">>, Status, 1),
            case ExitCode of
                0 ->
                    io:format("Output: ~s~n", [maps:get(<<"stdout">>, Status)]);
                _ ->
                    io:format("Error: ~s~n", [maps:get(<<"stderr">>, Status)])
            end;
        State when State == <<"timeout">>; State == <<"cancelled">> ->
            io:format("Job ~s~n", [State]);
        _ ->
            timer:sleep(1000),
            poll(JobId)
    end.

Initial Response

{
  "job_id": "job_1234567890_abc",
  "status": "pending"
}

Check the status and results of an asynchronous job. Poll this endpoint after submitting a job via /execute/async or /run/async.

URL Parameters

Example (Erlang)

#!/usr/bin/env escript
%%! -pa _build/default/lib/jsx/ebin

main(_Args) ->
    inets:start(),
    ssl:start(),

    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,

    JobId = "job_1234567890_abc",
    Url = "https://api.unsandbox.com/jobs/" ++ JobId,
    Headers = [{"Authorization", "Bearer " ++ ApiKey}],

    case httpc:request(get, {Url, Headers}, [], []) of
        {ok, {{_, 200, _}, _, Response}} ->
            Job = jsx:decode(list_to_binary(Response), [return_maps]),
            io:format("Status: ~s~n", [maps:get(<<"status">>, Job)]),
            case maps:get(<<"status">>, Job) of
                <<"completed">> ->
                    Result = maps:get(<<"result">>, Job),
                    ExitCode = maps:get(<<"exit_code">>, Result, 1),
                    io:format("Exit code: ~p~n", [ExitCode]),
                    io:format("Output: ~s~n", [maps:get(<<"stdout">>, Result)]);
                _ ->
                    ok
            end;
        {ok, {{_, 404, _}, _, _}} ->
            io:format("Job not found~n");
        {error, Reason} ->
            io:format("Request failed: ~p~n", [Reason])
    end.

Response (Completed)

{
  "job_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "status": "completed",
  "created_at": 1699564800,
  "started_at": 1699564801,
  "completed_at": 1699564805,
  "result": {
    "success": true,
    "stdout": "Hello from unsandbox!\n",
    "stderr": "",
    "exit_code": 0,
    "language": "python",
    "artifacts": [],
    "execution_mode": "pooled",
    "network_mode": "zerotrust",
    "total_time_ms": 4021
  }
}

Possible Status Values

• pending - Job queued, waiting to execute
• running - Job currently executing
• completed - Job finished (check result field)
• timeout - Job exceeded TTL limit
• cancelled - Job was cancelled via DELETE

List all active (pending or running) jobs for your API key. Useful for monitoring multiple async executions.

Example (Erlang)

#!/usr/bin/env escript
%%! -pa _build/default/lib/jsx/ebin

main(_Args) ->
    inets:start(),
    ssl:start(),

    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,

    Url = "https://api.unsandbox.com/jobs",
    Headers = [{"Authorization", "Bearer " ++ ApiKey}],

    case httpc:request(get, {Url, Headers}, [], []) of
        {ok, {{_, 200, _}, _, Response}} ->
            Jobs = jsx:decode(list_to_binary(Response), [return_maps]),
            lists:foreach(fun(Job) ->
                JobId = maps:get(<<"job_id">>, Job),
                Status = maps:get(<<"status">>, Job),
                Language = maps:get(<<"language">>, Job),
                io:format("~s: ~s (~s)~n", [JobId, Status, Language])
            end, Jobs);
        {error, Reason} ->
            io:format("Request failed: ~p~n", [Reason])
    end.

Response

{
  "jobs": [
    {
      "job_id": "job_1234567890_abc",
      "status": "running",
      "language": "python",
      "submitted_at": "2024-01-15T10:30:00Z"
    },
    {
      "job_id": "job_0987654321_xyz",
      "status": "pending",
      "language": "go",
      "submitted_at": "2024-01-15T10:29:45Z"
    }
  ]
}

Cancel a pending or running job. If the job is already executing, it will be terminated and partial output returned.

URL Parameters

Example (Erlang)

#!/usr/bin/env escript
%%! -pa _build/default/lib/jsx/ebin

main(_Args) ->
    inets:start(),
    ssl:start(),

    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,

    JobId = "job_1234567890_abc",
    Url = "https://api.unsandbox.com/jobs/" ++ JobId,
    Headers = [{"Authorization", "Bearer " ++ ApiKey}],

    case httpc:request(delete, {Url, Headers}, [], []) of
        {ok, {{_, 200, _}, _, Response}} ->
            Result = jsx:decode(list_to_binary(Response), [return_maps]),
            io:format("Cancelled: ~s~n", [maps:get(<<"message">>, Result)]),
            case maps:get(<<"result">>, Result, undefined) of
                undefined ->
                    ok;
                PartialResult ->
                    io:format("Partial output: ~s~n", [maps:get(<<"stdout">>, PartialResult)])
            end;
        {ok, {{_, 404, _}, _, _}} ->
            io:format("Job not found or already deleted~n");
        {error, Reason} ->
            io:format("Request failed: ~p~n", [Reason])
    end.

Response

{
  "message": "Job cancelled",
  "job_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
  "result": {
    "success": false,
    "stdout": "Partial output before cancel...",
    "stderr": "",
    "exit_code": -1,
    "language": "python",
    "artifacts": [],
    "execution_mode": "pooled",
    "network_mode": "zerotrust",
    "total_time_ms": 1523
  }
}

Execute code with automatic language detection via shebang. Send raw code as the request body with Content-Type: text/plain.

Request

• Content-Type: text/plain
• Body: Raw code with shebang (e.g., #!/usr/bin/env python3)

Query Parameters

Example (Erlang)

#!/usr/bin/env escript
%%! -pa _build/default/lib/jsx/ebin

main(_Args) ->
    inets:start(),
    ssl:start(),

    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,

    Url = "https://api.unsandbox.com/run",
    Headers = [
        {"Content-Type", "text/plain"},
        {"Authorization", "Bearer " ++ ApiKey}
    ],
    Code = "#!/usr/bin/env python3\nprint(\"Language auto-detected!\")",

    case httpc:request(post, {Url, Headers, "text/plain", Code}, [], []) of
        {ok, {{_, 200, _}, _, Response}} ->
            Result = jsx:decode(list_to_binary(Response), [return_maps]),
            io:format("Detected: ~s~n", [maps:get(<<"detected_language">>, Result)]),
            io:format("Output: ~s~n", [maps:get(<<"stdout">>, Result)]);
        {error, Reason} ->
            io:format("Request failed: ~p~n", [Reason])
    end.

Response

{
  "success": true,
  "stdout": "Language auto-detected!\n",
  "stderr": "",
  "exit_code": 0,
  "language": "python",
  "detected_language": "python",
  "job_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
  "artifacts": [],
  "execution_mode": "pooled",
  "network_mode": "zerotrust",
  "total_time_ms": 412
}

Submit code with automatic language detection and receive a job ID. Combines the convenience of /run with the flexibility of async execution.

Request

• Content-Type: text/plain
• Body: Raw code with shebang (e.g., #!/usr/bin/env ruby)

Query Parameters

Example (Erlang)

#!/usr/bin/env escript

main(_Args) ->
    inets:start(),
    ssl:start(),

    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,

    % Submit job
    Url = "https://api.unsandbox.com/run/async",
    Headers = [
        {"Content-Type", "text/plain"},
        {"Authorization", "Bearer " ++ ApiKey}
    ],
    Code = "#!/usr/bin/env ruby\nputs \"Running async with auto-detect!\"",

    {ok, {{_, 200, _}, _, Response}} = httpc:request(post, {Url, Headers, "text/plain", Code}, [], []),
    Job = jsx:decode(list_to_binary(Response), [return_maps]),
    JobId = maps:get(<<"job_id">>, Job),

    io:format("Job submitted: ~s~n", [JobId]),

    % Poll for results
    poll(JobId).

poll(JobId) ->
    ApiKey = case os:getenv("UNSANDBOX_API_KEY") of
        false -> "unsb-sk-test0-vault-unlck-12345";
        Val -> Val
    end,
    Headers = [{"Authorization", "Bearer " ++ ApiKey}],
    StatusUrl = "https://api.unsandbox.com/jobs/" ++ binary_to_list(JobId),

    case httpc:request(get, {StatusUrl, Headers}, [], []) of
        {ok, {{_, 200, _}, _, Response}} ->
            Status = jsx:decode(list_to_binary(Response), [return_maps]),
            case maps:get(<<"status">>, Status) of
                <<"completed">> ->
                    ExitCode = maps:get(<<"exit_code">>, Status, 1),
                    io:format("Detected: ~s~n", [maps:get(<<"detected_language">>, Status)]),
                    case ExitCode of
                        0 ->
                            io:format("Output: ~s~n", [maps:get(<<"stdout">>, Status)]);
                        _ ->
                            ok
                    end;
                State when State == <<"timeout">>; State == <<"cancelled">> ->
                    io:format("Job ~s~n", [State]);
                _ ->
                    timer:sleep(1000),
                    poll(JobId)
            end;
        {ok, {{_, 404, _}, _, _}} ->
            io:format("Job not found~n");
        {error, Reason} ->
            io:format("Request failed: ~p~n", [Reason])
    end.

Initial Response

{
  "job_id": "job_1234567890_abc",
  "status": "pending"
}

Job Result (via GET /jobs/{id})

{
  "job_id": "a7b8c9d0-e1f2-3456-ghij-789012345678",
  "status": "completed",
  "created_at": 1699564800,
  "started_at": 1699564801,
  "completed_at": 1699564802,
  "result": {
    "success": true,
    "stdout": "Running async with auto-detect!\n",
    "stderr": "",
    "exit_code": 0,
    "language": "ruby",
    "detected_language": "ruby",
    "artifacts": [],
    "execution_mode": "pooled",
    "network_mode": "zerotrust",
    "total_time_ms": 1234
  }
}

Upload files to your sandbox execution. Files are written to the working directory and can be accessed directly by filename.

File Object Schema

Example Request

{
  "language": "python",
  "code": "print(open('data.csv').read())",
  "input_files": [
    {
      "filename": "data.csv",
      "content": "bmFtZSxhZ2UKQWxpY2UsMzAKQm9iLDI1"
    }
  ]
}

Limits

• Maximum files: 10 files per execution
• Maximum total size: 10MB (decoded)
• Maximum single file: 5MB (decoded)
• Filename length: 256 characters max

File Access

Files are placed in the working directory. Access them directly:

• Python: open('data.csv')
• Node.js: fs.readFileSync('data.csv')
• Ruby: File.read('data.csv')
• Go: os.ReadFile("data.csv")

Security

• Files are isolated per execution
• Filenames cannot contain path separators (no / or ..)
• Files are deleted after execution completes