Agentstration

The open-source, self-hosted control plane for AI agents.

Agentstration lets you define governed agents, model profiles and tools, compose them into versioned Flows, distribute reusable Packs, and execute and track delegated work from an operations Console or the end-user Workplace.

It is built on the Microsoft .NET AI stack and currently executes agents through Microsoft Agent Framework (MAF), while keeping application contracts provider-neutral and cloud-optional. Real agents can run fully locally through Ollama, llama.cpp or LocalAI; no Azure subscription is required.

• Website: www.agentstration.io/en
• Documentation: docs.agentstration.io
• Project status: public alpha, under active 0.x development

What is implemented

Governed agent platform

• declarative, workspace-scoped Agents, model providers, Model Profiles, deployments, Extension registrations and tool catalogs;
• Ollama, llama.cpp and LocalAI integrations through autonomous, versioned AEP contributions;
• governed Tool execution with enablement checks, ordered hooks, workspace guards, human approval and durable audit records;
• local Secrets and Vault management;
• local accounts, external identity links, stable Principals, workspace memberships, scoped RBAC and security auditing.

Flows and durable execution

• editable Flow drafts, immutable published versions and observable Flow Runs;
• structured Direct, Routing and Workflow Flows with typed steps and transitions;
• Microsoft Agent Framework orchestration modes, including Sequential, Concurrent, Handoff, Group Chat and Magentic;
• durable interactive execution for text, choice, confirmation and tool-approval requests;
• persisted checkpoints, selected revisions and run traces so supported executions can be reconstructed after a restart.

Work Plane and Workplace

• durable Work Items, interactions, Tasks, Pending Actions, results, artifacts and notifications;
• Entries as governed user-facing access points to immutable Flow versions;
• workspace Dashboards that organize published Entries without exposing runtime details;
• a responsive, conversation-first Workplace that projects agent turns, progress, human input and outcomes;
• an operations Console for configuration, supervision, run inspection and governance.
• a generic Console Entry interaction surface that reuses durable conversations, tasks, pending actions, results and artifacts for Console-exposed Entries;
• a permission-aware Console Conversations view for returning to durable Entry interactions in the selected Workspace;
• Console Resource Plan review with saved per-agent profile choices, proposed changes, dependency graph, validation, and activity history.

Packs and automation

• immutable, explicitly scoped Source identities and versioned publisher definitions, per-Channel Agentstration compatibility, optional exact-digest publisher verification, plus a bounded AEP Git provider that pins explicit Channel refs to exact commits before materialization;
• offline ZIP Pack installation with deterministic publisher.name namespaces and retained provenance;
• Pack inventory, resource bindings, exact-source forks, local authoring and builds, replacement and modification-safe uninstall;
• Pack Studio and workspace composition for ordinary Agentstration resources—Packs distribute resources but are never executed;
• workspace-scoped schedule Triggers supporting one-time, interval and Quartz cron schedules, IANA time zones, occurrence history, misfire/concurrency policies and Run now;
• Triggers submit autonomous Work to a Flow, including namespaced Flows installed by Packs. They do not introduce a second runtime.

Architecture

Agentstration is a modular monolith with explicit Management, Runtime, Work and Flow boundaries:

• the Management Plane owns governed definitions and desired state;
• the Runtime Plane materializes and executes agents through provider-neutral contracts;
• the Work Plane receives, represents and tracks delegated work and its outcomes;
• the Flow module owns composition, publication, orchestration and durable Flow Runs.

Packs form a distribution layer above these boundaries. The repository produces multiple local hosts from one codebase: the operations Console and authoritative server, the standalone Workplace, the Work API and an Aspire AppHost. SQLite-backed stores keep the main module boundaries explicit. Resource Planning owns durable reviewed proposals outside executable Management state.

The Agentstration Extension Protocol SDK, conformance validator, CLI, samples and standalone Inspector are staged autonomously in aep/. AEP gives extensions versioned discovery, capability and option contracts without leaking provider-specific concerns into portable Agentstration resources.

Read the architecture overview and current capabilities reference for the detailed boundaries and guarantees.

Quick start

Requirements

• the .NET SDK selected by global.json, currently .NET SDK 10.0.300 with compatible feature-band roll-forward;
• Ollama, llama.cpp or LocalAI to execute real agents locally;
• optionally Docker for container-based local model or Compose workflows.

Run locally

git clone https://github.com/gbaudrit/agentstration.git
cd agentstration

dotnet run --project src/Agentstration.Web

Open the operations Console at http://localhost:5100. In local Development, the default http and https launch profiles enable the development profile from the versioned bootstrap catalog and create the public fixture admin / admin, Tenant dev, and Workspace default on a fresh instance.

The operations Console also has an independently hostable process shell. Keep the authoritative server running and start it from another terminal:

dotnet run --project src/Agentstration.Console.Web --launch-profile https

Open https://localhost:7190. Its Management, Work, Flow, and Runtime origins are configured independently under Agentstration:*Api:BaseAddress. Private BFF calls use a dedicated instance-bound workload credential. Local login creates an opaque secure cookie backed by server-side BFF state and revalidates the Principal and selected context with the authoritative server on every request. The Console now obtains short-lived internal delegations for server-side API calls to those origins. External OIDC login still depends on #204.

For a manually launched separated Console, provision a credential without displaying it:

./scripts/security/provision-bff-workload.ps1 -OutputPath ./.agentstration/bff-workload/console-bff/primary.key

Configure Agentstration:BffWorkload on Agentstration.Console.Web and Agentstration:BffWorkloadTrust on the authoritative Agentstration.Web with the same workload ID (console-bff), credential ID, credential-file path, and target/authoritative instance ID. Add a second credential entry for overlap, move the Console to it, then set Revoked=true on the old server entry. Aspire and Compose provision their development credential automatically; committed configuration never contains its value.

The authoritative server generates its RS256 delegation key in Data:Directory on first use. For a stable multi-instance deployment, configure Agentstration:InternalDelegation:SigningKeyFile to the same protected private-key file on every authoritative API replica. To rotate, switch to a new private-key file and list the old public-key PEM under Agentstration:InternalDelegation:PreviousPublicKeyFiles; retain it for at least the configured token lifetime (120 seconds by default), then remove it. The separated Console's in-memory session store is a single-replica default; a shared IBffServerSessionStore is required for session continuity across Console replicas. See ADR-0115 and ADR-0116.

Use --launch-profile http-NoBootstrap or --launch-profile https-NoBootstrap to start Development without applying initial profiles. These launch profiles retain the catalog path and selected profiles but set InitialBootstrapEnabled to false. Published applications, Production, and runs using --no-launch-profile do not activate the Development profile. Without declarative bootstrap, /bootstrap remains available to create the first global local administrator plus the initial Tenant and Workspace interactively.

When Agentstration.AppHost is the Visual Studio startup project, select its https profile for the default bootstrap or https-NoBootstrap to disable it for the orchestrated Console resource.

After initialization, a Platform administrator can open System > Bootstrap profiles to compose profiles in a defined order, preview every create, skip, conflict, or validation error, select an explicit Tenant or Workspace target when required, and confirm the application. Manual applications are retained in durable history. A profile declares its scope in a reserved profile.yaml:

apiVersion: agentstration.io/v1
kind: BootstrapProfile
metadata:
  name: workspace-tools
definition:
  displayName: Workspace tools
  description: Reusable tools and agents for one Workspace
  targetScope: workspace
  bindings:
    - name: agent-model
      targetKind: modelProfile
      displayName: Agent model
      description: Model Profile selected for the reusable agents
      required: true

Workspace profiles can declare typed bindings so their ordinary editable resources do not embed environment-specific names. The Console asks for each target before preview; API callers provide the same profile-qualified selections. A binding may define defaultTarget for non-interactive use. Only a structured reference object is substituted, never arbitrary YAML text:

definition:
  displayName: Support agent
  instructions: Answer support questions concisely.
  modelProfile:
    binding: agent-model
  runtimeProfile:
    name: maf-builtin
    namespace: default

Selections are included in the preview digest and retained as resource references in application history. They may target an existing resource or one planned earlier in the same composition. Secret bindings retain only the Secret reference; secret values are never copied into the profile, preview, or history.

A Workspace profile can install an existing local Pack while preserving Pack ownership and immutability. The archive path is relative to the profile directory; HTTP sources and replacement of an installed Pack are intentionally rejected:

apiVersion: agentstration.io/v1
kind: PackInstallation
metadata:
  name: standard-tools
definition:
  source:
    path: artifacts/standard-tools.zip
  bindings: []

A Workspace profile may also create ordinary ModelProvider, RuntimeProfile, ModelProfile, Agent, Flow, and Entry resources directly from their normal YAML manifests. Unlike resources installed from a Pack, these resources have no Pack provenance and remain editable through their usual Console and API surfaces. Files and YAML documents are evaluated in lexical order, so dependencies must precede their consumers: provider and runtime profile, then model profile, agent, flow, and entry. A Model Provider must reference an Extension Registration already available in the target Workspace. A published Entry targeting a Flow requires that Flow to already have, or create earlier in the same application, an active published version.

For example, this creates an editable Agent using resources declared earlier in the same profile:

apiVersion: agentstration.io/v1
kind: Agent
metadata:
  name: support-agent
definition:
  displayName: Support agent
  instructions: Answer support questions concisely.
  modelProfile:
    name: support-model
  runtimeProfile:
    name: local-runtime
  tools: []

In the Development environment, the complete interactive HTTP API reference is available at http://localhost:5100/swagger, backed by the OpenAPI document at http://localhost:5100/openapi/v1.json. Swagger supports the current Console session cookie and JWT bearer tokens; SignalR and MCP remain separate transports.

Managed is the normal execution mode. Configure an Ollama, llama.cpp or LocalAI provider and bind a Model Profile to run real agents entirely on your machine. The provider endpoint and selected model are resolved from Agentstration's persisted resources.

For a first UI exploration, automated test or diagnostic session without any model, use the deterministic fallback:

$env:AI__Provider = "Deterministic"
dotnet run --project src/Agentstration.Web

Deterministic mode produces reproducible simulated responses. It is not a substitute for a local model and is not the normal production path.

To run the end-user Workplace, keep the authoritative server running and start a second terminal:

dotnet run --project src/Agentstration.Workplace.Web

Open http://localhost:5180. The Workplace API defaults to the server at http://localhost:5100.

For Aspire orchestration and its local dashboard:

dotnet run --project src/Agentstration.AppHost

Or use one of the provider-specific Compose topologies. For Ollama:

docker compose -f deploy/compose/ollama.yml up --build

This topology includes Ollama, its AEP extension, the Utilities extension, and a persistent model volume. Pull models explicitly with docker compose -f deploy/compose/ollama.yml exec ollama ollama pull <model>; Compose never downloads one implicitly. The deploy/compose/llama-cpp.yml and deploy/compose/localai.yml topologies likewise include their inference server, matching AEP extension, Utilities, and persistent model storage. llama.cpp expects an explicitly supplied GGUF file; LocalAI starts with an empty model catalog. Each extension authenticates through an isolated Compose-owned SharedKeyFile volume. Set AI_PROVIDER=Deterministic for the explicit offline fallback. deploy/compose/base.yml retains the canonical deterministic extension topology without an inference server.

SQLite remains the standalone default. To start the optional PostgreSQL 17 variant, create the ignored environment file, replace its disposable development password, and combine a topology with the shared PostgreSQL overlay:

Copy-Item deploy/compose/.env.postgresql.example deploy/compose/.env.postgresql
docker compose --env-file deploy/compose/.env.postgresql -f deploy/compose/ollama.yml -f deploy/compose/postgresql.yml up --build

Replace ollama.yml with base.yml, llama-cpp.yml, or localai.yml to select another PostgreSQL-backed variant. PostgreSQL stores relational module data in seven schemas but leaves secrets, Data Protection keys, Pack archives, and Work artifacts on the existing file stores. Changing provider does not migrate SQLite data. Startup bootstrap is coordinated through a durable fenced initialization lease, but this does not by itself make every runtime subsystem safe for horizontally scaled operation. Readiness is exposed at /health/ready; /health remains liveness.

For Aspire, set Agentstration:Storage:Provider=PostgreSql. Its generated password is persisted in user-secrets and relational data is kept in the worktree-isolated Docker volume agentstration-<slot>-<instance-id>-postgresql; file-backed state remains under the slot data directory. See configuration for startup behavior, reset, troubleshooting, and backup guidance.

Aspire starts Agentstration's local AEP extensions against existing inference servers. The Microsoft Foundry extension is opt-in through Foundry:Enabled=true or the optional Compose overlay; each Model Provider supplies its own endpoints and downstream identity through AEP Value Bindings. It supports deployment discovery, text chat, streaming and governed Tool calls. See Foundry integration. Provider-specific Compose files isolate Ollama, llama.cpp, and LocalAI, with each topology owning its inference service and model storage. No topology downloads a model implicitly. Follow the local installation guide and model provider guide for provider-specific setup.

Build and test

dotnet build Agentstration.slnx --configuration Release
dotnet test --solution Agentstration.Tests.Fast.slnx --configuration Release --no-build --minimum-expected-tests 1
dotnet test --solution Agentstration.Tests.Integration.slnx --configuration Release --no-build --minimum-expected-tests 1

Browser-level UX smoke tests and the reusable capture runner live under automation/playwright. They start isolated local Console and Workplace hosts with deterministic AI. See Browser automation for setup and commands.

Warnings are treated as errors, .NET analyzers are enabled and NuGet audit findings fail restore. The fast and integration lanes together provide complete required functional validation while remaining offline and cost-free; real-provider and performance workloads are opt-in. See the test lane guide for project classification and focused commands.

Documentation

The published documentation at docs.agentstration.io tracks the current development branch and covers:

• getting started;
• concepts;
• architecture;
• reference;
• Architecture Decision Records;
• contributor guidance.

The Markdown and MDX files under docs/ are the source of truth; docs/site/ contains the Docusaurus renderer. To work on the site locally, follow Working on the documentation.

Project status

Agentstration is a public alpha under active 0.x development. Public APIs, resource contracts and package formats may still change. It is a product foundation, not yet a production multi-tenant release; planned capabilities and current limits are identified explicitly in the documentation.

Product versions follow Semantic Versioning and are published as immutable v<version> tags with matching technical notes under docs/releases/.

License

Agentstration is licensed under the Apache License 2.0. The license includes an explicit patent grant; trademarks and product names are not licensed except as required for customary attribution. See NOTICE for attribution information.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, the Code of Conduct and the Security policy before opening a substantial change.