Ploinky

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
$ echo 'PLOINKY_MASTER_KEY=change-me-to-a-random-secret' > .env
$ npm install
$ echo 'export PATH="$PATH:$HOME/Desktop/work/ploinky/bin"' >> ~/.bashrc
$ source ~/.bashrc
$ cd ~/Desktop/work
$ ploinky start explorer

PLOINKY_MASTER_KEY is required before Ploinky can start because it derives workspace secrets from that value. Any non-empty value works for local testing, but a long random value is recommended. You can keep it in the project .env file as shown above or export it in your shell.

The PATH line above points to the cloned Ploinky bin directory and makes ploinky available in new Bash sessions. If your clone lives somewhere else, replace $HOME/Desktop/work/ploinky/bin with that path. For Zsh, add the same line to ~/.zshrc.

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 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: By enabling an agent, it becomes part of the Ploinky workspace. The Ploinky server will expose the agent on a local port, which allows you to build applications that interact with your agents through a simple API on localhost. When you open the web interface, you will need to provide a token, which can be found in .ploinky/.secrets.

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