Ploinky

Isolated, controllable, and observable agent workspaces

Build and use agents inside controlled runtimes while Ploinky manages their lifecycle, routing, and observation without installing each agent's dependencies directly on the host.

The Ploinky Wiki is the canonical reference for project-specific terminology used throughout these guides.

Quick Start Demos

ploinky@workspace
🔒

Isolated Containers

Each managed agent runs in a separate runtime with explicit mounts, filtered environment values, and private routing.

📦

Repository System

Organize agents in repositories. Install or uninstall repository checkouts as needed.

🌐

Web Interfaces

Use agent CLIs through WebChat and reach admitted agent web routes through the authenticated Router.

🔧

Easy Configuration

Simple manifest.json defines container image, dependencies, and commands.

🚀

Development Workflow

Keep agent homes and workspace files persistent while inspecting runtimes through Ploinky lifecycle and log commands.

🔄

Readiness and Health

Activate routes only after the selected agent graph satisfies its declared readiness contract.

Getting Started

Prerequisites

Ploinky uses containers to run agents in isolated environments. Therefore, you need to have a container runtime installed on your system. Ploinky supports both Docker and Podman.

Docker

On Debian-based Linux distributions (like Ubuntu), you can install Docker with:

sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io

For other operating systems or more detailed instructions, please refer to the official Docker documentation.

Podman

On Debian-based Linux distributions (like Ubuntu), you can install Podman with:

sudo apt-get update && sudo apt-get install podman

For other operating systems or more detailed instructions, please refer to the official Podman documentation.

Lightweight Sandboxes (Optional)

On Linux, Ploinky can use bubblewrap (bwrap) for lightweight process sandboxing without full containers. On macOS, seatbelt (sandbox-exec) provides similar isolation. Set "lite-sandbox": true in an agent's manifest.json to auto-detect the host sandbox. To force podman/docker for testing, run ploinky sandbox disable.

Installation

$ git clone https://github.com/AssistOS-AI/ploinky.git
$ cd ploinky
$ npm install
$ echo 'export PATH="$PATH:/path/to/ploinky/bin"' >> ~/.bashrc
$ source ~/.bashrc
$ cd /path/to/workspace
$ ploinky start explorer

The managed Box initializes the workspace master key at .ploinky/master-key. The PLOINKY_MASTER_KEY process or .env input is reserved for direct core-development flows that deliberately manage that seed.

The PATH line points to the cloned Ploinky bin directory and makes ploinky available in new Bash sessions. Replace /path/to/ploinky and /path/to/workspace with your own locations. For Zsh, add the same line to ~/.zshrc.

View CLI Reference Learn Architecture

Introduction to Agents

In Ploinky, an "agent" is a tool that you can use and modify. It can be a simple script, a long-running service, a web application, or an LLM-powered coding tool.

Agents are organized in managed repositories, which can contain multiple agents. You can add repositories, enable the agents you need, and keep their runtime files separated from your project files.

Coding assistants can also be installed as Ploinky agents. For example, a codexAgent can run Codex inside a containerized environment, so its shell, package installs, and CLI configuration stay inside the agent home instead of directly mutating your host machine.

This is useful when a coding agent needs to inspect an unfamiliar project or install dependencies you do not fully trust. Running the agent in a container lets you keep the host workspace safer while still giving the agent a controlled place to work.

Using Agents

You can interact with agents in three main ways:

  1. Individually: You can run an agent's command-line interface directly using the cli command. For example, ploinky cli codexAgent opens the Codex agent CLI inside its containerized environment. Agents can accept JSON, natural language, files, or any other convention defined by their manifest.
  2. As a shell environment: You can enter an agent's container with ploinky shell <agentName>. This is useful when you want to inspect the runtime, run package managers, debug tool installation, or see the same filesystem and home directory the agent sees.
  3. Integrated with Ploinky: Enabling an agent records it in the enabled-agent registry; starting the workspace creates its admitted runtime and routes. Browser clients authenticate through the Router login flow, while agent-to-agent calls use generation-bound credentials that Ploinky delivers only to eligible isolated runtimes.

Usage

From within the project directory

When you are in the project directory, you can use the ploinky command directly. Here are the first steps to get you started:

  1. Run ploinky to initialize your workspace
  2. Start explorer agent: start explorer

Globally from any directory

To use ploinky from anywhere, you need to add its location to your shell's configuration file (e.g., .bashrc, .zshrc).

Add the following line to your ~/.bashrc or ~/.zshrc file, replacing ~/path/to/ploinky with the actual path to your ploinky directory:

export PATH="$PATH:~/path/to/ploinky/bin"

After adding the line, restart your shell or run source ~/.bashrc (or source ~/.zshrc). You can then use p-cli or ploinky from any directory. For example:

ploinky list agents