Projects

Create, start, stop, and delete Levee projects, and understand what the agent can see inside a project's sandbox

A project is a folder of work: a folder on your computer where the AI agent reads and writes files for one piece of work. Levee runs each project in its own sandbox, a sealed-off Windows container, so the agent sees only that folder and what you or your organisation allow.

Each project has its own sandbox, its own approvals, its own shared files, and its own audit trail. Two projects never share a sandbox, a remembered decision, or a signed-in website.

Where are projects stored?

New projects are created inside your project directory (Settings > Workspace > Default project directory).

By default this is a folder named LeveeProjects in your Windows user profile, for example C:\Users\alex\LeveeProjects.
It must be a folder on your own computer, inside your own user profile. Network shares, other people's profiles, and system folders are refused with Project root path is not allowed.

The reason: the project folder is the one place the agent can read and write directly, so Levee only allows folders you own. To let the agent use files kept elsewhere, such as a network share, share them with the project.

How do I create a project?

Click New project in the sidebar.
Type a name, for example q3-report.
Click Create.

The name becomes the folder name, so it cannot contain \, /, :, .., or other characters Windows does not allow in file names. A folder with the same name must not already exist in the project directory.

From the command line: levee project create q3-report.

How do I start and stop a project?

Starting a project opens its sandbox. Levee starts the container, applies your organisation's rules, and only then lets the agent work. Stopping it closes the sandbox.

In Easy mode, the sandbox starts when you send your first message. In Advanced mode:

Start: open the project and click Start (the play button), or use the project's Settings tab > Start Container. The status shows Starting…, then Running.
Stop: Settings tab > Stop Container.

From the command line: levee project start q3-report and levee project stop q3-report.

Only one project runs at a time

A computer runs one project at a time. If you start a second one, Levee shows "Another project is already running. Stop it, then start this one." If someone else's project is running on the same computer, you see "Another user's project is running on this computer. Try again once it has stopped."

If a stop is not confirmed

If Levee cannot confirm the sandbox has fully shut down, the status shows Shutdown unconfirmed and the sandbox's network restrictions stay in place. Try stopping again; see Project won't start if it continues.

Levee also refuses to start a project if it cannot apply its network rules. There is no "start without protection" option.

The project tabs (Advanced mode)

Tab	What it shows
Console	A terminal inside the running sandbox, in `C:\workspace`. Start the AI tool here, for example `claude` or `codex`.
Activity	What happened in the project: requests, approvals, refusals, and start and stop events. See Activity and audit.
Access Policy	File access (the files and folders you shared with the project), then the rules and remembered decisions that apply, grouped by type (HTTP / HTTPS, ODBC, Files, Tools, Other). Remembered decisions have a Revoke button.
Connected identities	Websites you signed in to on the agent's behalf. See Connected identities.
Settings	Status with Start Container / Stop Container, the project folder path, the Levee components active for the project, and Tools, where you turn AI tools on, upgrade or turn them off.

In Easy mode the same project opens as a chat instead.

Enabling AI tools for a project

AI tools (Claude Code, Codex CLI, GitHub Copilot CLI) are published by your administrator and turned on per project. In Easy mode, Levee turns on your preferred tool automatically on a new project. To do it yourself, in Advanced mode:

Open the project's Settings tab and find Tools.
Click Enable next to a tool. A dialog lists the internet addresses the tool needs, for example its vendor's service.
Click Approve and enable. You approve all the addresses or none; the tool is not turned on otherwise.

Good to know:

Turning a tool on or off while the project runs takes effect at the next start of the project.
The tool's version is fixed when you turn it on. When your administrator publishes a newer one, the tool shows Upgrade. Nothing changes until you click Approve and upgrade.
Your organisation's rules come first. If they block an address the tool needs, turning it on fails with Blocked by admin policy: ....
Turning a tool off removes only the addresses that tool added. Addresses you approved yourself stay.

Every change is recorded in the audit trail (tool.enable.approved, tool.upgraded, tool.disabled).

What can the agent see inside the sandbox?

The agent sees your project folder, the files you shared with the project, and the AI tools turned on for it. Nothing else on your computer is there: not your profile, your documents, other projects, or network shares you did not share.

Path in the sandbox	Access	Contents
`C:\workspace`	Read and write	Your project folder. The agent works here.
`L:\`	As you shared them	Files and folders you shared with the project.
`C:\tools`	Read only	The AI tools turned on for this project.
`C:\levee-config`	Read only	A guide that tells the agent how the sandbox is laid out, including where your shared files appear, and settings Levee writes for the agent.
`C:\certs`	Read only	The certificate the sandbox uses for Levee's inspection of web traffic.

The sandbox has no direct network access. Web traffic, AI model calls, database queries and searches all pass through Levee, which applies the rules and records them. The agent gets a placeholder key for the AI model that is useless outside the sandbox; the real key stays on your computer.

Details

The sandbox shell is PowerShell 7. The standard image includes Git, Python, and Node.js.
A project folder holds your files plus project.json (the project's name, 12-character id and creator), a .levee\ folder of Levee working data, and a .gitignore that excludes .levee/.
If Git is installed on the computer, Levee sets up version history (a Git repository) in the folder when it creates the project. When the project stops, Levee saves any unsaved changes to that history with the message Levee auto-save: <UTC timestamp> (author Levee), so you have a checkpoint of everything the agent changed. Without Git, this step is skipped.

How do I delete a project?

Deleting is done from the command line:

# Stop managing the project but keep its files on disk
levee project delete q3-report

# Delete the project and its folder, including its version history
levee project delete q3-report --delete-files

Without --delete-files, Levee removes only project.json; your files stay where they are. With --delete-files, the whole folder is removed.

If Levee cannot confirm that no sandbox for the project is still running, it refuses to delete the files: "Levee cannot confirm that this sandbox has no container still running, so it will not delete the project's files. Contact your administrator."

Project identifiers

Every project has a 12-character id (for example 3f9c1a7e42b0). Wherever the command line asks for a project, you can give its name, its id, or the start of its id if no other project shares it. levee project list shows both.

The Levee App Sharing Files