Perceptron Boxes

Boxes are computers you own and control through Perceptron. A box gives you and your Personas a real machine to work on: a live desktop, a shell, a filesystem, and a screen you can watch and capture. Personas drive boxes with computer use, clicking, typing, scrolling, and reading the screen the same way a human operator would.

You can attach boxes to Personas so they can automate tasks on your behalf, or use a box yourself for development, browsing, and testing.

Box kinds

Perceptron supports three kinds of boxes:

Host Box

A Host Box is the machine you are already using. When the Perceptron desktop app is running, your Personas can see its screen and, if you enable the shell, run commands on it. A Host Box shows as Online while the app is connected and Offline when it is not.

Because a Host Box is your personal computer, drive it with care. Prefer non-destructive actions while you are actively using the machine, and detach the box from Personas when you do not want them operating it.

Virtual Box

A Virtual Box is an isolated Linux Virtual Machine (VM) running locally on your hardware through QEMU. It has its own desktop environment, filesystem, and network, so Personas can work freely without touching your real machine. Virtual Boxes are free and you can run more than one.

When you create one you choose:

• Architecture: x86_64 or aarch64. The guest runs with native hardware acceleration when its architecture matches your host, and under software emulation otherwise (slower).
• vCPUs: 1 to 16
• Memory: 512 MB to 64 GB
• Disk: 8 GB to 512 GB

You can create, delete, start and stop a Virtual Box at any time from the Boxes page of the Perceptron app. The Maximum number of virtual Boxes is not capped, but is limited by the compute capacity of your local host machine

Cloud Box

A Cloud Box is a Linux Virtual Machine (VM) provisioned on Perceptron Cloud. It has its own desktop environment, filesystem, and network, so Personas can work freely without touching your real machine.

It is isolated and disposable, accessible from any of your logged in devices, and ideal when you want a machine that is always on regardless of whether your local machine is on and connected to the internet.

Cloud Boxes are billed hourly from your credits balance.

Adding a box

Open the Boxes page in the Perceptron app and click Add Box. You are prompted to choose the box type:

• Local: choose either Host Box (this device) or Virtual Box (a local VM with the architecture and sizing you pick). The Local option requires the Perceptron desktop app and is unavailable on the web app.

• Cloud: Cloud Boxes can be created on all Perceptron platforms including the desktop, mobile, and web apps. If creating a cloud box, choose a name and click Provision Cloud Box. Check Also save SSH key on my account if you want to share SSH access to the cloud Box between all your logged in devices.

Using boxes with Personas

Attach a box to a Persona from the Persona’s Boxes tab, where you can attach and detach any of your boxes. Once attached, the Persona can use the Boxes platform skill to operate and control that Box. It can observe the screen, control a virtual mouse pointer and keyboard, take screenshots or screen recordings to view them or send them to you, run shell commands, and verify results.

While you chat with a Persona, the Box Preview card in the chat sidebar shows a live screen preview of the Box it is currently working on.

Live Preview, Screenshots and Recordings

Open any box to see its Live Preview, a near real-time view of the box screen. The preview refreshes continuously while the detail view is open, and you can click it to open the full-screen Box Viewer. The Box Viewer has a pause control when you want to study a single frame.

Boxes also keep a rolling history of recent screenshots (the last 24 hours), which is useful for reviewing what a Persona did on a box after the fact.

Shell and SSH access

Host Boxes expose an optional SSH channel. Toggle Enable Shell in the box detail view to let Personas run shell commands on your local machine (disabled by default).

Cloud Boxes and Virtual Boxes are also reachable over SSH. Open the Box and click SSH Credentials to see the host, port, user, and key fingerprint.

The Perceptron native app then exposes a loopback tunnel you can use to connect to any Box:

The SSH session is end to end: no intermediary can read it.

Billing

Host Boxes and Virtual Boxes are free: they run on your own hardware. Cloud Boxes bill hourly from your credits balance while they exist, and stop billing when you delete them.

The current cloud Box rate is shown in the Add Box sheet and returned by the API as hourly_cost. See Billing for details.

API Reference

Boxes are managed primarily from the app. The list endpoint is also available to API clients that want to discover their boxes programmatically.

Authentication

Authorization: Bearer PERCEPTRON_API_KEY

List boxes

GET /api/boxes

curl https://perceptron.cloud/api/boxes \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "boxes": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "kind": "cloud",
      "name": "my-cloud-box",
      "platform": "ubuntu-24.04",
      "created_at": 1740000000,
      "status": "online",
      "hourly_cost": "$0.06"
    },
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "kind": "vm",
      "name": "my-virtual-box",
      "platform": "ubuntu-24.04",
      "created_at": 1740000000,
      "status": "stopped",
      "arch": "x86_64",
      "vm_cpu": 4,
      "vm_memory_mb": 4096,
      "vm_disk_gb": 32
    }
  ],
  "hourly_cost": "$0.06",
  "cloud_available": true
}

The top-level hourly_cost is the current Cloud Box rate, and cloud_available reports whether cloud boxes can be provisioned.