API Reference

ForeverVM

The ForeverVM class is a client for the ForeverVM API. Use it to manage your machines and for executing one-off instructions.

Tip

If you need to execute multiple instructions on a single machine or stream standard output, look at the Repl class.

Instantiate the client with your ForeverVM API token:

Python

from forevervm_sdk import ForeverVM

fvm = ForeverVM("your_forevervm_token")

JavaScript

import { ForeverVM } from '@forevervm/sdk'

const fvm = new ForeverVM({ token: "your_forevervm_token" });

If you store your API token in the FOREVERVM_TOKEN environment variable, the ForeverVM client will detect it:

Python

from forevervm_sdk import ForeverVM

fvm = ForeverVM()

JavaScript

import { ForeverVM } from '@forevervm/sdk'

const fvm = new ForeverVM();

Note

If you don’t have a ForeverVM API token yet, check out the getting started guide.

Methods

The following are all methods on the ForeverVM client:

Tip

If you use the Python SDK, all methods are synchronous by default. You can access asynchronous methods by appending _async to the method name. For example, fvm.whoami() would become fvm.whoami_async().

Create Machine

Creates a new machine.

Python

fvm.create_machine()

JavaScript

fvm.createMachine();

Output:

{
  "machine_name": "9kaTDWiKdAvaIZNE"
}

Creating with tags

Optionally, you can supply one or more tags when creating a machine, which can be used for filtering machines:

Python

fvm.create_machine(tags={"environment": "prod", "external_id": "12345"})

JavaScript

fvm.createMachine({ tags: { environment: "prod", external_id: "12345" } });

List Machines

Lists all the machines in your account.

Python

fvm.list_machines()

JavaScript

fvm.listMachines();

Output:

{
  "machines": [
    {
      "name": "9kaTDWiKdAvaIZNE",
      "created_at": "2025-02-13T21:48:24.740618Z",
      "running": false,
      "has_pending_instruction": false,
      "expires_at": null
    },
    {
      "name": "G32G3H3IGoTpG7ST",
      "created_at": "2025-02-13T21:44:18.329670Z",
      "running": false,
      "has_pending_instruction": false,
      "expires_at": null
    }
  ]
}

Listing by tags

Optionally, you can filter the list of machines by tags. A machine must match all the tags specified to be included in the list.

Python

fvm.list_machines(tags={"environment": "prod"})

JavaScript

fvm.listMachines({ tags: { environment: "prod" } });

Execute an Instruction

Executes an instruction on a machine.

Python

fvm.exec("1 + 1", "9kaTDWiKdAvaIZNE")

JavaScript

fvm.exec("1 + 1", "9kaTDWiKdAvaIZNE");

Parameters:

• code (string, required): the code to execute on the machine. It can be an arbitrarily long string of Python statements and expressions — something as short as 1 + 1 works, as well as a series of statements spanning multiple lines.
• machine_name (string, optional): the name of the machine on which to execute the instruction. If omitted, a new machine will be created.

Output:

{
  "instruction_seq": 0,
  "machine": "9kaTDWiKdAvaIZNE"
}

Get an Instruction Result

Returns the result of an instruction. If the instruction was an expression, the result can be found in the result.value property.

Python

fvm.exec_result("9kaTDWiKdAvaIZNE", 0)

JavaScript

fvm.exec("9kaTDWiKdAvaIZNE", 0);

Output:

{
  "instruction_id": 1,
  "result": {
    "value": "2",
    "data": null,
    "runtime_ms": 8
  }
}

Connect to a REPL

Creates a REPL session on a machine. For the API of the returned object, see the REPL reference.

Python

repl = fvm.repl("9kaTDWiKdAvaIZNE")

JavaScript

fvm.repl("9kaTDWiKdAvaIZNE");

Parameters:

• machine_name (string, optional): the name of the machine on which to create the REPL session. If omitted, a new machine will be created.

Authorization Troubleshooting

The whoami method returns information about the currently logged in account.

Python

fvm.whoami()

JavaScript

fvm.whoami();

Output:

{
  "account": "your_account_name"
}