Working with Projects

A Project contains local agent work, runs, teams, and memory. A GitHub repository is optional.

The Project Gallery

When you open Agentweaver, the first screen is the Project Gallery — a grid of cards, one per project.

Each card shows:

• Project name
• A GitHub mark in the card header when the project was created from GitHub
• Source repository (if created from GitHub)
• Working directory path on the server
• Availability badge — green Available or amber Unavailable

Unavailable projects

A project is marked Unavailable when its working directory has moved or is no longer accessible on the server. Create a new project for the replacement workspace, or delete the unavailable project record if it is no longer needed.

Click Open on any card to enter a project.

If no projects exist yet, the page shows an empty state with the same two creation actions.

Creating a project

Two creation paths are available from the Project Gallery toolbar:

Create blank project

1. Select Create blank project.
2. Enter a Name for the project.
3. Enter a Repository folder name. If the server has a configured data directory, the field shows it as a prefix — you only need to type the folder name inside it. Otherwise, enter a full absolute path to a git repository on the machine running the Agentweaver server.
4. Optionally choose a Blueprint to pre-equip the project with a team, one or more workflows, a review policy, and a sandbox profile. The blank dialog offers the same blueprint step as the GitHub dialog: a Templates tab to pick an existing catalog blueprint and a Generate tab to describe a goal and generate a custom one. To start empty, use the No blueprint action in the dialog footer. See Blueprints for details.
5. Select Create project.

Agentweaver creates a local git repository. Local agent work can continue without GitHub repository access.

Directory must be empty or new

The chosen directory must be empty or not yet exist. Agentweaver will not overwrite or adopt an existing non-empty directory.

Create from GitHub

1. Select Create from GitHub.
2. If prompted, select Authorize repository access.
3. Enter a Name for the project.
4. Search for a repository that the Repo App can access.
5. Enter a Repository folder name.
6. Optionally choose a Blueprint.
7. Select Create project.

Agentweaver clones the repository into the chosen directory and records the project with its GitHub origin. Its card then carries a GitHub mark in the gallery.

The repository picker shows only repositories available to both your GitHub account and the Agentweaver GitHub App installation. When the App is configured for selected repositories, use Open GitHub installation settings beside the relevant personal or organization account to change that installation's repository access. Multiple installations remain one combined repository list, with a separate settings action for each account.

Repository access

If repository access is not ready, select Authorize repository access. Agentweaver returns you to the current task after authorization. If the GitHub App is not installed for an account you can access, use the installation link supplied by Agentweaver. Agentweaver does not construct account-specific GitHub settings URLs.

Project settings

Open a project, then navigate to Settings (accessible from the project's navigation) to configure it.

Settings are organized in a left rail:

General

• Project name — rename the project.
• Default model — set the AI model used by default for this project's runs.

Access

Manage Agentweaver project members.

Repository

If a project started blank, local agent work remains available. Open Repository only when you want GitHub operations.

Select Set up repository access to create or connect a repository. Pull-request publishing requires this access. You can dismiss the optional setup card. Agentweaver remembers that choice for the current project and signed-in user. Unrelated project edits do not show it again; a repository requirement or readiness change does.

Sandbox policy

Controls how agent commands execute and what they can reach. Options include:

• Allowed/blocked shell commands
• Network access rules
• Destructive command gating
• Preview approval timeout — how long an agent-initiated live-preview request waits for approval. The default is 30 minutes; project owners can choose 1–1440 minutes. Existing projects inherit the 30-minute default.

Unattended

The Background section reports a project-scoped automation readiness status and a fixed reason code. It never reveals repository names, installation IDs, permission maps, or credentials. Its GitHub Copilot account control shows the effective background AI source: the verified login bound to this project, the platform-default GitHub Copilot account, or the deployment's custom-key provider when BYOK is active. Agentweaver shows the resolved provider, model, and scope before AI work starts; an active Azure BYOK provider can run Preview tasks, Direct, and Define Outcome without GitHub Copilot authorization. A Project Owner can start the separate Copilot App binding when that is the missing prerequisite. If a project binding is stale or its credential is missing, select Reconnect GitHub Copilot to repeat the same authorization flow and replace the broken binding. When readiness reports repo_app_installation_required and the deployment configures a Repo App slug, the page also shows a direct Install GitHub Repo App link.

Repository-less projects can run scheduled unattended workflows when their model provider and other automation prerequisites are ready. They do not need a Repo App installation merely to run background work. A GitHub-backed project has a separate repository prerequisite: repository operations and GitHub event triggers require the project's verified repository binding and Repo App installation. This repository requirement is independent of whether AI access comes from a project Copilot binding, platform Copilot binding, or active BYOK provider.

Once the prerequisites above are met, a Project Owner can turn scheduled/event-triggered automation on or off with the Activate automation/Deactivate automation control in this same section. Activating records which model-provider source (GitHub Copilot or BYOK) backs the automation at that moment; deactivating immediately stops new scheduled/event triggers from firing without deleting the project's schedules or event subscriptions, so re-activating resumes them. Only Project Owners can see or use this control — everyone else sees the read-only readiness status only.

Project Settings does not include legacy account-link controls, webhook provisioning, or webhook-secret controls. Repository event delivery is configured through the Repo App's App-level webhook.

After GitHub Copilot authorization, Agentweaver returns to the project's Background settings and shows the selected GitHub login. It does not show authorization data, repository or installation details, permissions, or credentials.

If that project's saved GitHub Copilot credential is missing, revoked, expired, or otherwise unusable, Agentweaver stops the run before creating its AgentHost sandbox and asks a Project Owner to reconnect the project's Copilot App. An active but stale project binding never falls back to a deployment-wide BYOK provider or platform-default Copilot account.

Danger Zone

Irreversible actions:

• Delete project — removes the project record only. The working directory and all files on disk are always preserved.

In-flight runs

If the project has active runs, Agentweaver will cancel them before deleting the project record.

Project availability

A project is Available when its working directory is accessible on the server. If the directory is moved or deleted:

• The project card shows Unavailable.
• Runs are blocked while the workspace is unavailable.
• Create a new project for the replacement workspace or delete the unavailable record if it is no longer needed.