How to Integrate Pentagi with Other Systems: REST APIs, Docker Sandboxes, and Custom LLM Providers

Pentagi exposes REST and GraphQL APIs, API-token authentication, Docker sandbox endpoints, and a pluggable LLM provider interface to integrate with CI/CD pipelines, security orchestration platforms, and custom dashboards.

The vxcontrol/pentagi repository is architected as a self-contained micro-service platform designed for external automation. You can integrate Pentagi with other systems at three distinct levels: HTTP APIs for language-agnostic access, direct Go SDK imports for native extensions, and event streams for real-time observability.

REST and GraphQL API Endpoints

Pentagi provides full CRUD operations for flows, tasks, containers, and logs through HTTP endpoints. The router initialization in backend/pkg/server/router.go (lines 73-81) wires all handlers, CORS middleware, and static assets, exposing endpoints like GET /api/v1/flows and POST /api/v1/containers.

For interactive exploration, the server hosts a GraphQL Playground alongside the REST API. The schema definition resides in backend/pkg/graph/schema.graphqls, while TypeScript types are auto-generated in frontend/src/graphql/ for client consumption. External scripts and CI pipelines can call these endpoints directly without browser interaction.

Authentication Methods

API Token Authentication

For programmatic access, Pentagi implements short-lived JWT-style tokens scoped per user and role. The token service defined in backend/pkg/server/services/api_tokens.go (lines 32-39) exposes CRUD endpoints for managing these credentials. Tokens are signed using the server-wide COOKIE_SIGNING_SALT environment variable.

To authenticate requests, create a token via POST /api/v1/tokens and include the header Authorization: Bearer <token> on every subsequent API call.

OAuth 2.0 Single Sign-On

For browser-based and mobile clients, Pentagi supports OAuth 2.0 via Google and GitHub providers. The flow redirects users to /auth/authorize, identical to standard OAuth implementations, allowing seamless integration with enterprise identity providers and web front-ends.

Docker Sandbox Integration

Pentagi’s penetration-testing capabilities rely on on-demand isolated containers. The internal Docker client provides programmatic access to this sandbox environment.

The SpawnContainer method in backend/pkg/docker/client.go (lines 54-60) handles the complete lifecycle: building temporary working directories, pulling base images when necessary, and configuring network settings. Each container is linked to a specific flow via database.Container records.

External systems can trigger sandbox creation through the POST /api/v1/containers endpoint or by importing the Go SDK and calling docker.SpawnContainer directly within a Go application.

Custom LLM Provider Plugins

You can extend Pentagi to support proprietary or custom LLM backends by implementing the provider.Provider interface. All provider implementations reside under pkg/providers/<name>/, with registration logic centralized in backend/pkg/providers/provider.go.

To add a new provider, implement the required methods (Type, Model, Call, and CallWithTools) and register the implementation using provider.Register. You must also update the whitelist in backend/pkg/server/models/providers.go to expose the new provider through the REST API configuration endpoints.

Observability and Event Streaming

Pentagi publishes real-time telemetry through Langfuse and OpenTelemetry integrations. By setting the LANGFUSE_BASE_URL or OTEL_HOST environment variables in backend/pkg/config/config.go (lines 18-22), the system automatically emits spans and traces during flow execution.

The controller.NewFlowWorker in backend/pkg/controller/flow.go (lines 10-23) creates observation spans during flow orchestration, allowing downstream monitoring solutions to track container execution, LLM provider calls, and task completion in real-time.

Practical Integration Examples

Creating a Flow via REST API

First, obtain an API token:

curl -X POST https://pentagi.example.com/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-pipeline","ttl":3600,"role_id":1}' \
  -u admin@example.com:adminpassword

Then initiate a new penetration test flow:

curl -X POST https://pentagi.example.com/api/v1/flows \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"title":"WebApp Pen-Test","model":"gpt-4o","provider_name":"openai","provider_type":"openai"}'

Spawning Containers with the Go SDK

For direct integration within Go applications, import the internal Docker client:

package main

import (
    "context"
    "log"

    "github.com/vxcontrol/pentagi/pkg/config"
    "github.com/vxcontrol/pentagi/pkg/docker"
    "github.com/vxcontrol/pentagi/pkg/database"
    "github.com/docker/docker/api/types/container"
)

func main() {
    cfg, _ := config.LoadConfig()
    dc, err := docker.NewDockerClient(cfg.DockerSocket, cfg.DockerNetwork, cfg.DataDir, cfg.PublicIP)
    if err != nil {
        log.Fatalf("docker init: %v", err)
    }

    contCfg := &container.Config{
        Image: cfg.DockerDefaultImageForPentest,
        Cmd:   []string{"nmap", "-sV", "example.com"},
    }
    hostCfg := &container.HostConfig{AutoRemove: true}

    cont, err := dc.SpawnContainer(context.Background(),
        "pentagi-nmap-42",
        database.ContainerTypeTool,
        42,
        contCfg,
        hostCfg,
    )
    if err != nil {
        log.Fatalf("spawn: %v", err)
    }
    log.Printf("container %s started", cont.Name)
}

Implementing a Custom LLM Provider

Register a new provider by implementing the interface:

package myprovider

import (
    "context"
    "github.com/vxcontrol/pentagi/pkg/providers/provider"
    "github.com/vxcontrol/pentagi/pkg/providers/pconfig"
)

type MyProvider struct{}

var _ provider.Provider = (*MyProvider)(nil)

func (p *MyProvider) Type() provider.ProviderType { return provider.ProviderCustom }

func (p *MyProvider) Model(opt pconfig.ProviderOptionsType) string {
    return "my-model"
}

func (p *MyProvider) Call(ctx context.Context, opt pconfig.ProviderOptionsType, prompt string) (string, error) {
    // Implement external API call logic
    return "model answer", nil
}

func init() {
    provider.Register("myprovider", provider.ProviderCustom, func(cfg pconfig.ProviderConfig) provider.Provider {
        return &MyProvider{}
    })
}

Summary

• REST and GraphQL endpoints in backend/pkg/server/router.go provide full CRUD access to flows, tasks, and containers for external automation.
• API-token authentication via services.NewTokenService enables secure, scoped programmatic access using JWT-style tokens signed with COOKIE_SIGNING_SALT.
• Docker sandbox integration exposes the docker.SpawnContainer method for on-demand container orchestration linked to specific flow IDs.
• Custom LLM providers implement the provider.Provider interface and register in pkg/providers to extend backend capabilities beyond OpenAI and Anthropic.
• Observability hooks automatically emit OpenTelemetry and Langfuse traces when OTEL_HOST or LANGFUSE_BASE_URL are configured.

Frequently Asked Questions

How do I authenticate API requests to Pentagi from a CI/CD pipeline?

Create a dedicated API token using the POST /api/v1/tokens endpoint with a specific TTL and role ID, then include the token in the Authorization: Bearer <token> header for all subsequent requests. The token service implementation in backend/pkg/server/services/api_tokens.go handles JWT creation and validation against the server's signing salt.

Can I trigger Docker containers in Pentagi from external security tools?

Yes. External systems can either call the POST /api/v1/containers REST endpoint or import the Go SDK to invoke docker.SpawnContainer directly. The method signature accepts container configurations, host configurations, and a flow ID to link the sandbox instance to a specific penetration test workflow.

What is required to add a proprietary LLM backend to Pentagi?

You must implement the provider.Provider interface defined in backend/pkg/providers/provider.go, specifically the Call and CallWithTools methods, then register your implementation using provider.Register. Additionally, add your provider type to the whitelist in backend/pkg/server/models/providers.go to enable selection through the REST API configuration endpoints.

How does Pentagi expose execution telemetry to monitoring systems?

Pentagi automatically publishes OpenTelemetry spans and Langfuse traces when you configure the OTEL_HOST or LANGFUSE_BASE_URL environment variables. The flow controller in backend/pkg/controller/flow.go creates observation spans during orchestration, allowing real-time tracking of container execution and LLM provider interactions in downstream APM tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}