Ploinky

Getting Started

Install with the bootstrap script

The installer detects Linux or macOS, checks Node.js, Podman and Git, installs or upgrades what it can, clones Ploinky when needed, and adds the ploinky command to your PATH:

curl -fsSL https://www.ploinky.com/install.sh | bash

The script asks for confirmation before installing anything. It reuses an existing checkout when one is present, otherwise it clones Ploinky into ~/.local/share/ploinky/src. If ploinky is already on your PATH it leaves it untouched; otherwise it adds the checkout's bin directory to your PATH. When it cannot install a prerequisite automatically it prints the manual commands and continues, and it finishes by telling you to run ploinky start explorer from your workspace.

Manual installation

Ploinky runs its rootless outer Box with Podman; Docker and arbitrary remote engines are unsupported for the outer Box. Pick your platform:

node --version     # need v22 or newer
podman --version   # need 5.4.0 or newer
git --version

sudo apt-get update
sudo apt-get install -y git podman uidmap passt conmon crun catatonit bubblewrap

git clone https://github.com/AssistOS-AI/ploinky.git
cd ploinky
echo "export PATH=\"\$PATH:$(pwd)/bin\"" >> ~/.bashrc
source ~/.bashrc

cd /path/to/workspace
ploinky start explorer

node --version     # need v22 or newer
podman --version
git --version

brew install node@22 git podman
brew link --overwrite --force node@22
podman machine init
podman machine start

git clone https://github.com/AssistOS-AI/ploinky.git
cd ploinky
echo "export PATH=\"\$PATH:$(pwd)/bin\"" >> ~/.zshrc
source ~/.zshrc

cd /path/to/workspace
ploinky start explorer

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 for testing, run ploinky sandbox disable.

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. Replace /path/to/workspace with your own location.

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