Skip to main content

Agents

Agents execute the work you author in the Workshop. They expose CPU, GPU, memory, and storage resources to the Forge platform and provide the runtime environments that run Aleph scripts, manage datasets, and stream results back to your workspace.

Agent Types​

The Forge currently ships with one agent type: Personal agents.

You can deploy personal agents on machines you control—laptops, lab workstations, or dedicated servers. They let you decide exactly which hardware powers your workloads and how much capacity you dedicate to experimentation or production jobs. Personal agents do not have to reside on the same network or physical location as the browser using the Workshop; they communicate over Kothar’s secure connections and can bridge offices, datacenters, and remote networks. Each agent maintains a persistent link to the Kothar API and automatically reconnects if the machine reboots or the network drops briefly.

Support for shared and managed agent pools is on the roadmap, so you will be able to mix and match deployment models as your team grows.

Requirements​

To run a personal agent you need:

  • A Mac, Windows, or Linux machine (x86_64 or ARM64).
  • A Docker-compatible runtime installed.
  • Reliable internet access, including HTTPS connectivity to https://api.kotharcomputing.com.

Install a Docker Runtime​

Install Docker or a compatible container engine before provisioning an agent:

  • macOS: install Docker Desktop for Mac. After installation, launch Docker Desktop once so it can provision the virtualization layer and confirm the engine is running from the menu bar (whale icon).
  • Windows 10/11: install Docker Desktop for Windows. Ensure that either WSL 2 or Hyper-V is enabled when prompted. Start Docker Desktop after installation and wait for the status indicator to turn green before proceeding.
  • Linux: install the Docker Engine packages provided by your distribution (e.g. sudo apt-get install docker.io on Ubuntu or sudo dnf install docker on Fedora). Enable and start the service with sudo systemctl enable --now docker. Verify permissions so your user can run docker ps without elevated privileges, or prefix subsequent commands with sudo.

Once Docker is available, you are ready to register and launch an agent.

Creating and Launching a Personal Agent​

  1. Open the Workshop and navigate to the Agents view in the Primary Sidebar. You can perform this step from any browser; it does not have to be on the machine that will host the agent.
  2. Click the + icon to create a new agent.
  3. Choose a descriptive name (e.g. Main Office, Lab Notebook, or Cluster-GPU-01) so teammates can recognize the hardware behind the agent.
  4. The Workshop generates a Docker command tailored to your workspace and the chosen agent. Copy the command and paste it into a terminal on the target machine.
  5. Run the command. The container downloads the base image, authenticates with Kothar, and establishes a secure connection to the Forge.
  6. When the console returns, head back to the Workshop to confirm the agent shows a green status indicator - you may have to wait a couple of seconds for it to turn green. You can close the terminal window; the agent continues to run in the background.

Agents appear in the list with their current state, detected CPU threads, and memory capacity. Open its context menu for additional actions.

Updates and Resource Management​

Agents update themselves automatically. They check for new versions every hour and download runtimes on demand. If you suspect you are not on the latest version, restart the container via the agent’s context menu in the Workshop; the agent pulls fresh binaries as it reconnects. Updates never interrupt running activities.

Personal agents can host multiple executions, jobs, and background tasks simultaneously. However, they share hardware resources across those activities. For best performance, limit one intensive activity at a time and minimize other workloads on the host machine. Advanced users may tailor the Docker command with resource constraints to impose CPU, memory, or GPU limits, but be aware that overly restrictive settings can prevent scripts from running successfully.

Troubleshooting​

  • Verifying authenticity: the agent’s base image is published at https://github.com/KotharComputing/agent. You can verify signatures with Sigstore using the instructions in the repository README. The runtime validates every component it downloads before execution, guaranteeing the integrity of Kothar binaries.

  • Connection or runtime issues: use the agent’s context menu in the Workshop and select Troubleshoot to retrieve the latest logs. The guidance often highlights configuration or connectivity issues. If problems persist, try the Restart option to restart the container, or Reset token to revoke credentials and recreate the agent. Resetting is also useful when moving an agent to a different machine.

Best Practices​

  • Keep the host machine updated and ensure Docker starts automatically after a reboot so agents reconnect without manual steps.
  • Use descriptive naming conventions to differentiate agents by location or hardware profile.
  • When retiring an agent, use the context menu to delete it, which revokes credentials and removes it from the workspace.

With agents in place you can execute scripts, schedule jobs, and stream outputs directly into the Workshop.