Documentation.

From installation to your first project.

Installation

You need macOS 14 or later and a main account authorized to use sudo. One installer supports Apple Silicon and Intel.

  1. Download the macOS installer and open the .pkg file.
  2. Follow the macOS installer.
  3. Open Finder → Applications → Open Cube.

The installer places the app in /Applications. It does not create accounts or change directory permissions. No Xcode or ZIP extraction is needed.

First-time setup

In the app, choose Skonfiguruj Maca (Set up your Mac). Terminal will open with guided prompts. You do not need to type commands. The native app currently uses Polish labels.

  1. Confirm creation of the standard agent account if it does not exist. macOS will ask for a new password for this account.
  2. Set up the project folder /Users/Shared/AgentWork and access to it.
  3. Review the option to protect your main home folder. Accepting blocks the agent’s access to that entire folder.
  4. Confirm installation of Codex and Claude in the agent user’s home folder.

Prompts require YES or INSTALL. An existing agent account and its password are preserved. You can return to the setup guide in the app’s settings.

Signing in to tools

After setup, return to the app. Choose Zaloguj Codex (Sign in to Codex) or Zaloguj Claude (Sign in to Claude), then follow the tool’s instructions in Terminal.

Each tool has its own sign-in and billing terms. The app does not copy keys or sessions from your main account. Sign-in buttons are also available in the Agenci (Agents) section.

Your first project

  1. Open Projekty (Projects) and choose Dodaj projekt (Add project).
  2. Select an existing folder inside AgentWork, or choose Izolowana kopia repozytorium (Isolated repository copy) and a trusted source repository.
  3. Select the project, then choose Uruchom Codex (Launch Codex), Uruchom Claude (Launch Claude) or Terminal.

An isolated copy contains committed Git history. It does not copy uncommitted changes or credential configuration. Changes do not automatically sync back to the source repository.

Session status and errors appear in the project details. Zatrzymaj (Stop) sends SIGTERM; processes running independently in the background may need to be stopped separately.

Permissions and security

The agent runs as a standard macOS user. macOS and sudo handle passwords; the app does not store them. The agent account does not receive administrator rights.

This alpha has no publisher certificate or Apple notarization. If macOS blocks the file, try opening it, then go to System Settings → Privacy & Security. If you trust the project, choose “Open Anyway”. Apple’s instructions.

A separate account is not a full sandbox. Actual access is determined by macOS permissions; Safe and Network profiles do not block network access. The project has not undergone an independent security audit.

Full security model · Report a vulnerability privately

Troubleshooting

  • Codex or Claude is missing: reopen setup and choose tool installation, then start a new session.
  • The agent can access private folders: open setup and review the option to protect your main home folder.
  • Cannot write to an older project: setup does not recursively change existing files. Create a new isolated copy or review permissions.
  • Status is unknown: diagnostics may require authentication in Terminal. Check the Agenci (Agents) section for details.

Detailed guide and diagnostic commands (Polish)

Updates and removal

Download and run the new installer. The app in /Applications will be updated; the agent account, projects and settings are preserved.

If an older version was installed in ~/Applications, open the new copy from the system Applications folder. The older copy is not automatically removed.

You can move the app to the Trash. This does not remove the agent account, tools, projects or permissions added during setup. How to undo the remaining changes (Polish).