Skip to main content

Synentra in 5 Minutes (Quickstart)

This quickstart takes you through a complete Synentra request flow: start the gateway, register an AI agent, authenticate it, assign an intent-aware policy, and proxy a request to an upstream API.

By the end of the guide, you will have a working local Synentra instance that evaluates an agent request before forwarding it to the destination API.

What you will do​

  1. Create a policy that permits read-only requests.
  2. Start Synentra in Docker.
  3. Verify that Synentra and its required services are healthy.
  4. Register an agent and assign the policy to it.
  5. Exchange the agent credentials for a short-lived JWT.
  6. Send a governed request through the Synentra proxy.

Prerequisites​

Before you begin, make sure you have:

  • Docker version 24 or later
  • curl or another HTTP client
  • A terminal that supports the commands shown below
  • An internet connection for downloading the Synentra container image, the intent model on first use, and the sample upstream response
  • A basic understanding of HTTP and REST APIs
note

The commands use port 7080. If that port is already occupied, map a different host port, such as -p 7081:7080, and use http://localhost:7081 in the remaining commands.

1. Create an intent-aware policy​

Create a directory named policies in your current working directory:

mkdir -p policies

Inside that directory, create a file named todo-management.json with the following content:

{
  "name": "todo-management",
  "default": "Deny",
  "rules": [
    {
      "name": "allow-todo-queries",
      "priority": 100,
      "effect": "Allow",
      "reason": "Todo queries are permitted",
      "conditions": [
        {
          "field": "intent.label",
          "operator": "eq",
          "value": "safe_read"
        }
      ]
    }
  ]
}

This policy uses a deny-by-default approach:

  • Requests classified with the safe_read intent are allowed.
  • Requests that do not match the rule are denied.
  • The rule priority is 100, which determines its evaluation order relative to other rules in the same policy.
  • The reason is recorded with the decision, making the outcome easier to understand and audit.
Why use intent instead of only the HTTP method?

Two requests can use the same HTTP method and path while expressing different goals. Synentra evaluates the semantic intent of the request so that policy decisions can account for what the agent is attempting to do—not only the shape of the HTTP call.

2. Start Synentra​

Run Synentra and mount the local policy directory into the container:

docker run -d \
  --name synentra \
  -p 7080:7080 \
  -v "$(pwd)/policies:/app/policies:ro" \
  ghcr.io/synentra/synentra:latest

The :ro suffix mounts the policy directory as read-only, preventing the container from changing your policy files.

This command starts Synentra with:

  • The Gateway API available at http://localhost:7080
  • An embedded SQLite database, so no external database is required
  • The built-in DistilBERT-based intent classifier
  • The todo-management policy loaded from the mounted directory
First startup can take longer

On its first run, Synentra may need to download the latest Synentra Intent Community Edition model. Startup time therefore depends on your network speed. Subsequent starts should be faster after the required image and model assets are available locally.

To watch the startup process, run:

docker logs -f synentra

Press Ctrl+C to stop following the logs. This does not stop the container.

3. Verify the installation​

Check the health endpoint before registering an agent:

curl -s http://localhost:7080/health

A healthy instance returns a response similar to:

{
  "status": "Healthy",
  "healthCheckDuration": "00:00:00.0123456"
}

The exact duration will vary. Continue when the reported status is Healthy.

If Synentra is still initializing, wait a few seconds and try again. If it does not become healthy, inspect the logs with docker logs synentra.

4. Register your first agent​

An agent is the authenticated workload that sends requests through Synentra. Register an agent by sending a POST request to the /agents endpoint:

curl -X POST "http://localhost:7080/agents" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "todo-agent",
    "ownerId": "team-productivity",
    "clientSecret": "replace-with-a-strong-secret"
  }'

The fields identify and authenticate the workload:

  • name is a human-readable agent name.
  • ownerId identifies the team or service responsible for the agent.
  • clientSecret is used to obtain an access token.

The response includes an agentId in UUID format. Copy it and refer to it as <AGENT_ID> in the remaining steps.

Protect agent credentials

The secret above is suitable only as a quickstart placeholder. For real deployments, generate a strong, unique secret, store it in a secret manager, never commit it to source control, and avoid exposing it in shell history or logs.

5. Assign the policy to the agent​

Associate the todo-management policy with the newly registered agent:

			 
curl -X PUT "http://localhost:7080/agents/<AGENT_ID>/policy" \
  -H "Content-Type: application/json" \
  -d '{
    "policyName": "todo-management"
  }'

Replace <AGENT_ID> with the UUID returned in Step 4.

This assignment tells Synentra to evaluate requests from this agent against the todo-management policy. Because the policy defaults to Deny, only requests that satisfy an explicit allow rule can proceed.

6. Obtain an access token​

Synentra agents authenticate with short-lived JSON Web Tokens (JWTs). Exchange the agent ID and secret for an access token:

curl -X POST "http://localhost:7080/tokens" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "<AGENT_ID>",
    "clientSecret": "replace-with-a-strong-secret"
  }'

Replace <AGENT_ID> with the UUID returned in Step 4. The clientSecret must exactly match the value used when the agent was registered.

The response contains an accessToken:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Copy the token and refer to it as <ACCESS_TOKEN> in the next step. The token is short-lived; request a new one if it expires.

7. Send a governed request​

Send a request through Synentra's /proxy endpoint. This example retrieves a sample to-do item from JSONPlaceholder, a public test API:

curl -X GET \
  "http://localhost:7080/proxy/https://jsonplaceholder.typicode.com/todos/1" \
  -H "Content-Type: application/json" \
  -H "Synentra-Authorization: Bearer <ACCESS_TOKEN>"

Replace <ACCESS_TOKEN> with the JWT returned in Step 6.

Before forwarding the request, Synentra:

  1. Validates the agent's JWT.
  2. Resolves the registered agent and its assigned policy.
  3. Builds semantic context from the request.
  4. Classifies the request intent.
  5. Evaluates risk, trust, and policy conditions.
  6. Records the decision for auditing.
  7. Forwards the request only when the final decision is Allow.

For this read-only request, the classifier should identify a safe read intent and the policy should permit it. A successful proxied response is similar to:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

The response originates from the upstream API, but it reaches the agent only after Synentra authorizes the request.

External test service

JSONPlaceholder is used only to demonstrate proxying. Its availability and response content are outside Synentra's control. In production, replace the example URL with an API you own or trust.

8. Clean up​

Stop and remove the quickstart container:

docker stop synentra
docker rm synentra

Because this quickstart does not mount a persistent data volume, the embedded SQLite data is removed with the container. The local policies/todo-management.json file remains on your machine.

What you accomplished​

You have completed a minimal end-to-end Synentra flow:

Agent registration → Policy assignment → JWT issuance → Intent classification → Policy decision → Upstream API

You can now replace the public test endpoint with your own upstream API, add more policy rules, and configure production-grade storage, authentication, observability, and secret management.

Troubleshooting​

The container does not start​

Inspect the container logs:

docker logs synentra

Common causes include:

  • Port 7080 is already in use: Map a different host port, for example -p 7081:7080, and update the remaining URLs.
  • The container name already exists: Remove the previous container with docker rm synentra, or choose another value for --name.
  • The image cannot be downloaded: Confirm that Docker can access ghcr.io and that your network or proxy configuration permits the download.
  • The model download fails: Confirm that the container has outbound network access, then restart it and inspect the logs for the model source and error details.

The health endpoint is unavailable​

Confirm that the container is running:

docker ps --filter "name=synentra"

If it has stopped, include stopped containers and inspect its logs:

docker ps -a --filter "name=synentra"
docker logs synentra

If the container is running but still initializing, allow additional time for the first model download.

The policy is not found​

Verify that the policy exists at policies/todo-management.json in the directory from which you started the container. Then confirm the mount:

docker inspect synentra

Also check that the JSON is valid, the policy's name is exactly todo-management, and the assigned policyName uses the same spelling and capitalization.

After changing a policy during this quickstart, restart the container so the updated file is loaded:

docker restart synentra

Agent authentication fails​

Check that:

  • <AGENT_ID> is the UUID returned by the registration request.
  • The token request uses the same client secret used during registration.
  • The Synentra-Authorization header contains Bearer, followed by one space and the complete token.
  • The access token has not expired.

The proxied request is denied​

A denial shows that Synentra evaluated the request but the final decision was not Allow. Check the container logs and verify that:

  • The agent has the todo-management policy assigned.
  • The request is classified as safe_read with sufficient confidence.
  • The policy was loaded successfully and contains the allow rule.
  • The request method, destination, and content match the operation you intended.

Do not weaken a production policy merely to suppress a denial. Review the decision context and add the narrowest rule that represents the action you intend to permit.

The upstream API cannot be reached​

Test the upstream service directly:

curl -s https://jsonplaceholder.typicode.com/todos/1

If the direct request succeeds but the proxied request fails, verify that the Docker container has outbound network access and inspect the Synentra logs.

Next steps​

  • Replace JSONPlaceholder with an API in your own environment.
  • Add separate rules for read, write, administrative, and destructive intents.
  • Configure persistent storage before using Synentra beyond local evaluation.
  • Integrate an external identity provider for production authentication.
  • Enable centralized audit logs, metrics, and distributed tracing.
  • Configure human-in-the-loop review for high-impact requests that should not be automatically allowed or denied.
Last updated on

Was this helpful?