Runcrate

Open a port or a range on every machine in this environment, from anywhere or only from the addresses you list. Only workspace owners and admins can change the firewall. Applies to running machines within about a minute. Prefer listing your own addresses over anywhere for anything that is not meant to be public. A web app served over HTTPS through create_instance_link needs no firewall rule.

Add an SSH public key to your workspace. Paste the contents of a .pub file (e.g., ssh-ed25519 AAAA... user@host).

Get the workspace balance and how long it lasts: creditsBalance, activeUsageCost, floating_balance_usd (the balance net of what running instances have used so far, in USD), burn_usd_per_hour (what the running instances cost together) and runway_hours (hours the floating balance lasts at that rate; null when nothing runs), which says how soon the balance needs topping up before running work runs out of credit.

Get a spending breakdown for your workspace.

Cancel a job: stops its machine and billing, and the status becomes cancelled. Cancelling a cancelled job changes nothing; a job that already ended another way cannot be cancelled. Returns the job. cost_usd covers the machine's whole time, not only the command's: from when its machine came up until it stopped, so setup before the command (pulling the image, waiting for the GPU driver, unpacking code) is included, at each machine's hourly rate (cost_per_hour is the current one's) and with every attempt added up. It is in USD to six decimal places, so a short run is not shown as $0, and while the job runs it is the cost so far. The charge on the billing page can differ slightly: machines billed by the minute are charged whole minutes, including about 30 seconds of teardown, and time some hosts report offline is not charged.

Cancel every job of a group that has not ended: their machines and billing stop, and waiting jobs never start. Jobs that already ended are left as they are. Returns the group, with cost_usd for all of its jobs (each job's machine time, every attempt, in USD to six decimal places).

Find the machines a multi-node GPU cluster can be created on right now. create_cluster needs an offer_id from here. A cluster is bought by the machine, never by the GPU: each offer is one kind of machine with gpus_per_node GPUs (1, 2, 4 or 8), and has an offer_id, location, interconnect (kind and label; an ethernet note says what the link suits), deployment_type, host_tier, the stacks it can run, min_nodes, max_nodes, allowed_node_counts (when present, the only sizes it can be created at), nodes_available (null when only a launch can tell), node (one machine's vcpus, memory_gb, storage_gb, vram_gb), hourly_rate_per_node (one machine) and hourly_rate (the whole cluster at node_count machines). Show the user the location, interconnect, GPUs per machine and hourly_rate with the per-machine price before creating. Leave gpus_per_node out to see every size of machine. Offers change as capacity moves, so use a fresh one. Community hosts are left out unless include_community is true; pass volume true when the cluster will get a storage_id.

Create a GPU cluster: node_count machines with the same GPUs on one private network, with SSH between them, a /shared folder on every node (not on container machines), and optionally Slurm, Kubernetes or Ray installed across them. It suits work that spreads over several machines; one machine is create_instance. Needs an offer_id from cluster_offers. A cluster is all or nothing: every machine starts or none does, and nothing is billed for a cluster that could not start. Billing starts when every machine is up, at hourly_rate_per_node for each machine (hourly_rate for the whole cluster), and runs until delete_cluster; there is no auto stop. The balance must cover one hour of the whole cluster, at least $10. Returns the cluster with status provisioning; get_cluster shows status ready once it is up (installing while the software installs). Errors: an offer that is gone, or that cannot run this stack or volume, lists the current offers (ask the user before picking another); no capacity means nothing was created. If the environment has reached its monthly budget the launch fails: do not retry, tell the user.

Deploy a new GPU instance. Provide a name and either gpu (auto-picks cheapest) or type_id from list_gpu_types. Optionally attach an SSH key by ID for manual ssh -i access, and a storage volume by storage_id to boot with its files. For unattended or long-running work, set max_runtime_minutes and idle_shutdown_minutes: when either fires the instance is terminated (not paused), so copy results off before then. Once it is running, commands reach it through ssh_execute or the CLI (runcrate ssh ). If the environment has reached its monthly budget the launch fails: do not retry, tell the user.

Serve one TCP port of a running instance at its own HTTPS link, for a web app or API listening over plain HTTP on 0.0.0.0. Pick who can open it: "workspace" (default: signed-in members of this workspace, who open it from the Runcrate dashboard), "public" (anyone with the URL) or "ips" (only the addresses in sources). Needs no firewall rule. Not for port 22 or Runcrate's own ports; one link a port, up to 10 an instance. Workspace owners and admins, and whoever launched the instance, can add links. An instance started before the firewall existed must be started again first.

Schedule an instance or a job to start later: once at run_at, or on a recurring cron in a timezone. Give exactly one of run_at or cron. spec is the launch itself, with the same fields as creating an instance (kind instance) or running a job (kind job). ALWAYS set spec.max_runtime_minutes: it is required, and the machine is stopped (billing ends) when it runs that long. A schedule fires within about 2 minutes of its time, in the current environment, and bills like a launch made then. Each run launches as you through this agent sign-in: if the sign-in ends (signed out or revoked), the schedule is paused with last_status credential_revoked. Recurring runs must be at least 15 minutes apart, and an environment holds at most 50 schedules (200 per workspace). Env values in spec (env, env_vars) are write-only: list_schedules shows only their names (env_keys). launch_script and startup_commands are shown to everyone in the environment by list_schedules; keep tokens in the environment secrets (set in the dashboard). Returns the schedule with next_run_at. After it fires, list_schedules shows last_status and last_error; update_schedule pauses, resumes or retimes it, and run_schedule_now starts it at once.

Create a new persistent storage volume.

Terminate a cluster: every machine stops together and billing for the whole cluster ends. One node cannot be stopped on its own. Files on the machines and in /shared are deleted, except what a volume keeps in /shared/volume, so copy results off first. Returns the cluster with status terminating, or terminated once done.

Terminate a running instance. Stops billing immediately.

Remove an HTTPS link from list_instance_links: its URL stops working within seconds and the port closes to Runcrate's proxy within about a minute.

Delete a job that has ended, with its logs and saved outputs; it is gone from list_jobs. A job still queued, starting or running cannot be deleted until cancel_job has stopped it. Volumes are not touched.

Delete a schedule so it never fires again. Instances and jobs it already started keep running.

Delete a storage volume.

Download a file from a running instance. Returns the file content as a string. Uses keyless SCP. Docs: https://www.runcrate.ai/docs/instances/connecting#file-transfer

Upload a file to a running instance. Provide the file content as a string and the remote path. Max 10MB. Uses keyless SCP. Docs: https://www.runcrate.ai/docs/instances/connecting#file-transfer

Get the workspace's auto-recharge: enabled, threshold_usd (the balance that triggers a top-up), target_usd (the balance it tops up to), and last_failure_reason and last_failure_at when the last automatic top-up failed.

Get one cluster: status, stack_status and stack_detail (why the software install failed, if it did), hourly_rate (whole cluster) and hourly_rate_per_node (one machine), billing.billed_since (when every machine came up) and billing.nodes_billed, resize (workers can be added or removed), and nodes, each with rank, role (head is rank 0), instance_id, status, stage, overlay_address, gpus, ip and ssh_command (null until the cluster is up; on a machine with no public address of its own, ssh_command goes through a gateway host and port). A node's instance_id works with ssh_execute, file_upload and file_download. connection has head_ssh, the hostfile, MASTER_ADDR, MASTER_PORT, NCCL_SOCKET_IFNAME and ready-made torchrun, mpirun and deepspeed commands (plus sbatch, kubectl_tunnel or ray_tunnel for those stacks). Also shared (/shared on every node, or available false on container machines), the last 50 events, and last_test, the latest NCCL test result.

Get the kubeconfig of a ready cluster whose stack is kubernetes. Its server is https://127.0.0.1:6443, so kubectl on the user's computer needs the returned tunnel command (an SSH port forward to the head) running first. Returns { kubeconfig, tunnel }: save kubeconfig to a file and set KUBECONFIG to it. It grants admin on the cluster, so treat it as a secret. kubectl also runs without a tunnel through ssh_execute on the head node.

Check an environment's monthly budget: the cap, what it has spent this month (UTC, GPU instances plus inference) and what is left. At 100% of the budget, launches in that environment fail, its running instances are stopped and its API keys stop serving inference until the month ends. Budgets can only be set or changed by a workspace owner or admin in the Runcrate dashboard, not from here.

Get detailed information about a specific instance, including its max runtime and idle stop settings, auto_stop_at (when max runtime will terminate it), stop_reason (why it stopped: user, max_runtime, idle, budget, low_balance, failed or system), its kind (deployment_type: vm, baremetal or container), who runs it (host: "Datacenter" or "Community host"), its firewall (status and rules; null on a container, which has none) and its HTTPS links (links).

Get one job: status, exit_code, error, started_at, ended_at, cost_per_hour and cost_usd (every attempt added up; final once the job has ended), attempts, tags and group_id. Statuses: queued (waiting for a machine: queue_reason says why, no_capacity, budget, max_parallel or volume_busy, and next_attempt_at when it is tried again), starting (machine launching), running (command started), then one final state that never changes: succeeded (exit code 0), failed (non-zero exit_code, or exit_code null and error says why, such as a reached budget, no capacity within capacity_wait_minutes, or a machine that failed with no retries left), cancelled, or timed_out (an attempt ran past max_runtime_minutes). A retried job goes back to queued with attempt one higher. cost_usd covers the machine's whole time, not only the command's: from when its machine came up until it stopped, so setup before the command (pulling the image, waiting for the GPU driver, unpacking code) is included, at each machine's hourly rate (cost_per_hour is the current one's) and with every attempt added up. It is in USD to six decimal places, so a short run is not shown as $0, and while the job runs it is the cost so far. The charge on the billing page can differ slightly: machines billed by the minute are charged whole minutes, including about 30 seconds of teardown, and time some hosts report offline is not charged.

A job's timeline, oldest first: [{ at, kind, detail, attempt }]. Kinds: created, queued, launch_attempt, launch_failed, machine_up, driver_wait_start, driver_ready, code_fetch_start, code_fetch_end, image_pull_start, image_pull_end, started, exited, retrying, artifacts_uploaded, stopped. Use it to see where a job spent its time or why it failed before its command ran (no capacity, the GPU driver, the code or the image).

Get a group of jobs started by run_job with count or params: how many are in each status (status_counts), max_parallel and cost_usd, the cost of all of them so far (each job's machine time, every attempt, in USD to six decimal places). list_jobs with group_id lists its jobs.

Read a job's output (stdout and stderr combined). The first read is after 0, and each later one passes the returned cursor as after. follow: true waits up to 25 s for new output instead of returning at once. done is true once the job has ended and all output was read; its status, exit_code and cost are in get_job. chunks are raw fragments in order, not lines: join their text as is. A response holds up to about 1 MB. Logs are capped at 10 MB per job: the first 5 MB and the newest output are kept, and truncated is true when the middle was dropped.

A job's GPU use while its command ran, oldest first: [{ at, gpus: [{ util, mem_used_mb, mem_total_mb }] }], one point per step seconds, util the average percent and memory the peak over the step. get_job has the totals (gpu_util_avg, gpu_mem_peak_mb). Low util on a long job means the GPU mostly waited: check data loading or the batch size.

Get one call to a model by its request id (the X-Request-Id header of the answer, or the id from list_requests; a completion id chatcmpl- works too): status, outcome, took_ms, ttft_ms, steps (where the time went before the answer), tokens, tokens_per_second, finish_reason, tool_calls, cost, end_user, session and tags. A failed call has error.message, error.api_said (the API's own words for an input error) and error.next_step: do what next_step says, then retry. finish_reason "length" means the answer hit max_tokens: raise it. Not found means it is older than 30 days, from another environment, or not a request id. With include_body, also body: the prompt and answer when the environment saves them (Settings > Environments, "Save prompts and answers"), else body.saved false.

Check the live status of an instance. Syncs with the provider.

List the GPU clusters in the environment, newest first: id, name, status (provisioning, installing, ready, degraded, terminating, terminated, failed), node_count machines of gpus_per_node x gpu_type, location, interconnect, stack (none, slurm, kubernetes or ray), hourly_rate for the whole cluster and hourly_rate_per_node for one machine. Active clusters only unless status is all. A cluster's nodes are not in list_instances; get_cluster lists them.

List the environments this connection can use. A signed-in agent works in the one environment picked at sign-in, so that is the one listed. Environments are created, deleted and switched in the Runcrate dashboard (https://runcrate.ai/dashboard/settings/environments); to work in another, the user reconnects Runcrate and picks it.

List the firewall rules of this environment: which inbound ports its machines accept, over TCP or UDP, and from which addresses (sources). Everything else is closed. A new environment allows only SSH (port 22) from anywhere. Changes reach running machines within about a minute. A machine started before the firewall existed shows firewall.status "unmanaged" in get_instance and keeps its ports as they were until it is started again. An HTTPS link to a web app on an instance is create_instance_link, not a firewall rule.

List available GPU instance types with pricing. Use this to find what GPUs are available before creating an instance. Each type has a kind, deployment_type: vm (a virtual machine), baremetal (a whole bare-metal server) or container (a GPU container on a shared datacentre host: SSH and a few published ports only, no firewall, HTTPS links public and only on its published ports, no prepaid terms). Tell the user which kind a type is when it matters for their work. Datacenter machines only, unless include_community is true: then community hosts too, each with host "Community host" (A community host is run by an independent host, not a datacenter: the host operates the hardware and can access the machine, and it is not available on reserved terms.). Only set include_community when the user asked for community hosts.

List the HTTPS links of an instance: each serves one port of the instance at https://-.runcrate.app, with a valid certificate, to workspace members (access "workspace"), anyone with the URL ("public"), or listed addresses ("ips").

List all GPU instances in your workspace. Returns name, status, GPU type, kind (deployment_type: vm, baremetal or container), who runs it (host: "Datacenter" or "Community host"; A community host is run by an independent host, not a datacenter: the host operates the hardware and can access the machine, and it is not available on reserved terms.), IP, and cost.

List the files a job kept: everything its command wrote under $RUNCRATE_OUTPUT_DIR (/workspace/outputs) is uploaded when the command ends, whatever its status, up to 5 GB and 1000 files, and kept 30 days. Returns [{ path, bytes, sha256 }]. read_job_artifact returns one. A job still running has none yet.

List jobs, newest first, with status, command, GPU, exit_code and cost_usd. A job runs one command on its own GPU machine (run_job starts one). Filter by tag, a name substring (q) or a group (group_id) to find earlier runs. cost_usd covers the machine's whole time, not only the command's: from when its machine came up until it stopped, so setup before the command (pulling the image, waiting for the GPU driver, unpacking code) is included, at each machine's hourly rate (cost_per_hour is the current one's) and with every attempt added up. It is in USD to six decimal places, so a short run is not shown as $0, and while the job runs it is the cost so far. The charge on the billing page can differ slightly: machines billed by the minute are charged whole minutes, including about 30 seconds of teardown, and time some hosts report offline is not charged.

List calls to Runcrate's models (chat, embeddings, images, speech, /v1/messages, /v1/responses) from this environment, newest first, kept 30 days: model, status, outcome, took_ms, ttft_ms, tokens, tokens_per_second, finish_reason, tool_calls, cost, end_user, session and tags. Prompts and answers are never stored. outcome: "error" finds failures: each failed call carries error.message (what happened) and error.next_step (what to do about it), and get_request with an id has its timing. Filter by session to read one agent run's calls (newest first), end_user for one of your users, tag for "key=value" pairs sent in X-Runcrate-Tags. Without from it covers the last 24 hours. When next_cursor is not null, pass it as cursor for the next page. Docs: https://www.runcrate.ai/docs/api-reference/model-calls/list-model-calls

List the schedules in the current environment, newest first: kind, spec (env values hidden, env_keys shows their names), run_at or cron and timezone, enabled, next_run_at, run_as and run_as_credential (user, api_key or agent: who each run launches as, and through what), and the last run: last_run_at, last_status (launched, failed, skipped_budget, skipped_overlap, no_access or credential_revoked), last_error, last_instance_id or last_job_id, run_count. A schedule whose scheduled runs failed 5 times in a row is paused (enabled false, last_error says so); once the cause is fixed, update_schedule resumes it.

List the names of the variables a machine launched in the environment gets, and where each comes from, never a value: key, sensitive, updated_at, source and active. source is "runcrate" for a secret set in Runcrate, or the environment's secret manager ("doppler:/", "infisical:/", "1password:"), whose names are those of its last read; active is false when a Runcrate secret of the same name overrides a manager's. A manager's names carry source_status (ok, failing, not_checked) and, when failing, source_error: while it fails, every launch in the environment is refused with "Secret manager unreachable". Every instance and job launched in the environment gets these as environment variables, so a command can read $HF_TOKEN without the value ever passing through you. Values set for one launch (run_job variables, a schedule spec's env or env_vars) win over all of them. Secrets are added, changed and removed only in the Runcrate dashboard (https://runcrate.ai/dashboard/settings/secrets) by a workspace owner or admin. A secret manager (Doppler, Infisical or 1Password) is connected once at https://runcrate.ai/dashboard/settings/integrations and linked to an environment on the Secrets page; no agent can connect or link one. When a command needs a secret that is not listed, ask the user to add it there, or to link their secret manager (they will need a Doppler service token, an Infisical machine identity, or a 1Password service account; the page walks them through it); never ask them to paste a value to you. When a source is failing, tell the user its source_error and to check it at the integrations page.

List SSH keys in your workspace.

List available regions for storage volumes.

List available OS templates for instances.

List all persistent storage volumes in your workspace. A volume's id is the storage_id create_instance takes to boot with its files.

Score one answer of a model called through the Runcrate inference API, by its request id (the X-Request-Id response header, or the completion id chatcmpl-). Send exactly one of thumbs ("up" or "down"), rating (1 to 5) or score (-1 to 1), with an optional label such as "helpful" or "wrong_format" and a comment. The rating shows with the request in the dashboard (Models > Observability) and can be filtered on there. Rating the same request again replaces this agent's rating. The request must be from the environment this session acts in and from the last 30 days.

Read one file a job kept (a path from list_job_artifacts). A text file up to 1 MB comes back inline as text; a larger or binary file comes back as url, a download link valid for an hour. Docs: https://www.runcrate.ai/docs/api-reference/jobs/download-a-job-output

Remove a firewall rule from list_firewall_rules: its ports close on every machine in this environment within about a minute. Removing the SSH rule cuts off SSH from outside.

Run a job again as a new job, on a fresh machine, with any run_job field changed, e.g. {"gpu_count": 2} or {"max_runtime_minutes": 240}. The variables of the first run are reused when you submitted it (they are never shown); anyone else sends them again as changes.variables. changes.variables is merged over them. Returns the new job, with rerun_of set, followed the same way as a run_job job.

Start an NCCL all-reduce test across every GPU on every node, once every machine of the cluster is up, to measure how fast the machines move data together before a long run. It uses every GPU, and the cluster is billed meanwhile as always. One test runs at a time per cluster; it takes a few minutes and at most 10. Returns the test with status running. The result is in get_cluster (last_test) once its status is passed or failed: result.sizes has the bus bandwidth in GB/s (busbw_gb_s) per message size, peak_busbw_gb_s the best, and result.note why it stopped early on a slow link.

Run one shell command as a job on its own fresh GPU machine. The command runs under bash in /workspace, and the machine stops (billing ends) as soon as the command exits. Billing is the machine's per-hour rate from when it is running until it stops, setup included. ALWAYS set max_runtime_minutes to a realistic upper bound for the command: a job that runs longer is stopped as timed_out. PREFER a list for gpu, e.g. ["H100", "A100-80GB:2", "L40S"]: the GPUs are tried in order, and with no capacity for any of them the job waits (status queued, queue_reason no_capacity, next_attempt_at) up to capacity_wait_minutes (default 30) instead of failing. To send code, pass files (path to text, up to 1 MB in all) or code.git (a repository and ref): it is put in /workspace/code before the command starts, and the command runs there. An agent with a shell and the Runcrate CLI can send a whole directory instead: runcrate run --code . -- . To keep results, write them to $RUNCRATE_OUTPUT_DIR (/workspace/outputs): they are kept 30 days after the job (up to 5 GB), whatever its status; list_job_artifacts and read_job_artifact return them. Or pass storage_id: the volume's files are in /workspace, and files written under /workspace are saved to the volume when the machine stops. For long or flaky work set max_retries: a machine that fails is replaced and the command runs again (RUNCRATE_JOB_ATTEMPT says which attempt), so write checkpoints to the volume and resume from them. count (or params, one variables object per job) runs many copies at once as a group (RUNCRATE_JOB_INDEX, RUNCRATE_JOB_COUNT), max_parallel at a time. The machine also gets the environment's secrets (list_secrets shows their names); variables of the same name win over them. Returns the job (status starting while its machine launches, or queued while it waits), or for count or params the group with its jobs. Its output is in get_job_logs (from after 0, each returned cursor as the next after; follow: true waits up to 25 s for new output; done is true at the end), and its status, exit_code and cost_usd in get_job. Statuses: queued, starting, running, then succeeded, failed, cancelled or timed_out. cancel_job stops a job early; rerun_job runs it again with changes. A retried call is not run twice: the job it already started is returned. The command starts once the GPU driver answers: on machines that install it after boot the job waits in starting for up to 20 minutes, and if the driver is still not ready then, the command runs anyway (usually failing on its GPU calls) and the job log says so. get_job_events shows each setup step. cost_usd covers the machine's whole time, not only the command's: from when its machine came up until it stopped, so setup before the command (pulling the image, waiting for the GPU driver, unpacking code) is included, at each machine's hourly rate (cost_per_hour is the current one's) and with every attempt added up. It is in USD to six decimal places, so a short run is not shown as $0, and while the job runs it is the cost so far. The charge on the billing page can differ slightly: machines billed by the minute are charged whole minutes, including about 30 seconds of teardown, and time some hosts report offline is not charged.

Launch a schedule's instance or job right now, whether the schedule is enabled or paused, billed like any launch. Its next_run_at does not move; last_status and run_count record the run. Returns the schedule and the instance or job it started.

Turn auto-recharge on or off and set when it charges the saved default card: when the balance falls below threshold_usd, it tops up to target_usd. threshold_usd and target_usd are required even to turn it off. Needs the billing permission on this sign-in and a workspace owner or manager behind it; target_usd cannot exceed this sign-in's daily top-up cap (TOPUP_CAP_REACHED), and with no saved card the answer is NO_PAYMENT_METHOD. Returns the settings as get_auto_recharge does.

Change when a running or starting instance stops on its own. Extend max_runtime_minutes before starting a job that will outlast the current auto_stop_at (get_instance shows it), and set max_runtime_minutes and idle_shutdown_minutes on any instance you leave working unattended. Max runtime counts from when the instance started running, so pass the total minutes, not extra minutes; a change never stops it sooner than 2 minutes from now. Pass null to turn a limit off; leave a field out to keep it. Either limit terminates the instance (not paused). Returns the instance with its new auto_stop_at.

Run a command on a running instance via SSH. Uses keyless SSH certificates. Returns the command output.

Add credit to the workspace balance by charging its saved default card (the only card it can use; cards are added in the dashboard, never here). This spends real money. It needs the billing permission on this sign-in, which a workspace owner or manager turns on in the dashboard's API keys page; without it the answer is BILLING_PERMISSION_REQUIRED. Each sign-in has daily and monthly top-up caps (UTC); past one the answer is TOPUP_CAP_REACHED with what is left. Answers status: succeeded (balance_usd is the new balance), processing (top_up with the same idempotency_key again reads its status), requires_action (nothing is charged yet: give your user confirm_url, which a workspace owner or manager opens signed in to confirm the payment before expires_at; the same idempotency_key then reads the result) or declined (reason and message say why; tell your user).

Change a firewall rule from list_firewall_rules: its ports, protocol, sources or description. Fields you leave out stay as they are; sources replaces the whole list. Applies to running machines within about a minute.

Change a schedule; only the fields you pass change. Pause with enabled false, resume with enabled true (a recurring schedule resumes from its next time after now; a one-off needs its run_at still in the future, or pass a new run_at). Passing run_at makes it a one-off and passing cron makes it recurring, so pass at most one of them. spec replaces the whole launch: send every field again, env values included (they are write-only), and keep max_runtime_minutes set. Recurring runs must be at least 15 minutes apart. Changing spec or timing (run_at, cron, timezone), or overlap, or resuming, makes the schedule run as you through this sign-in from then on; pausing or renaming does not.