Getting Started

This guide takes you from a fresh Python environment to a running JarvisCore agent in under ten minutes. It covers installation, initial configuration, and your first working agent.

---

Requirements

JarvisCore requires Python 3.10 or later. No infrastructure is required to run a minimal agent. The first working example in this guide uses only an LLM API key.

Docker is optional. It is used by the local infrastructure commands:

• jarviscore nexus up starts the local Nexus broker and gateway for OAuth2 credential management
• jarviscore memory init starts the local Athena memory stack
• remote sandbox deployments may run the execution service in a container

Local browser automation uses Playwright directly and does not require Docker. If you are not starting local infrastructure or a containerized sandbox, Docker is not needed.

---

Installation

pip install jarviscore-framework

To install optional extras for specific capabilities:

P2P MeshWebRedisBrowser AutomationRAGResearchAthena MemoryAzure Blob StoragePrometheus MetricsFull

pip install "jarviscore-framework[p2p]"

Enables distributed multi-node agent deployments via the SWIM gossip protocol and ZMQ transport. Required when P2P_ENABLED=true.

pip install "jarviscore-framework[web]"

Adds FastAPI, Uvicorn, and BeautifulSoup4. Required to run the built-in dashboard, chat endpoints, and FastAPI integration.

pip install "jarviscore-framework[redis]"

Enables distributed workflows, cross-session agent state, and peer routing via Redis. Required when REDIS_URL is set.

pip install "jarviscore-framework[browser]"
playwright install chromium

Enables BrowserSubAgent and Playwright-based web interaction tools. Required when BROWSER_ENABLED=true.

pip install "jarviscore-framework[rag]"

Adds local vector search (FAISS) and sentence-transformers for embedding-backed research and knowledge retrieval.

pip install "jarviscore-framework[research]"

Full researcher stack: installs browser + rag + BeautifulSoup4. Everything ResearcherSubAgent needs for deep web research.

pip install "jarviscore-framework[memory-athena]"

No extra Python dependencies. Athena is called over HTTP. Run the Athena service separately, then set ATHENA_URL=http://localhost:8080.

pip install "jarviscore-framework[azure]"

Adds the Azure Storage Blob client for the registry storage backend and azure_storage atoms.

pip install "jarviscore-framework[prometheus]"

Exposes a /metrics endpoint for operational dashboards and alerting.

pip install "jarviscore-framework[full]"

Installs every optional dependency. Use for production deployments where you need all capabilities enabled.

---

Scaffold Your Project

Run jarviscore init to create the initial project structure and a pre-populated .env.example:

jarviscore init

This creates:

.env.example: environment variable template

Copy the example to create your working configuration:

cp .env.example .env

---

Configure an LLM Provider

Configure exactly one provider by adding the appropriate variables to your .env file.

Existing Prescott entitlementAnthropic ClaudeGoogle GeminiAzure OpenAILocal / vLLM

If Prescott Data has already issued your organization a promotional entitlement, set it directly:

.env

JARVISCORE_PROMO_TOKEN=jc_trial_...

This is limited hosted inference access, not an upstream provider API key. There is currently no public self-service enrollment page.

.env

CLAUDE_API_KEY=sk-ant-...
CLAUDE_MODEL=claude-sonnet-4

.env

GEMINI_API_KEY=AIza...
GEMINI_MODEL=gemini-2.0-flash

.env

AZURE_API_KEY=...
AZURE_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_DEPLOYMENT=gpt-4o
AZURE_API_VERSION=2024-10-21

.env

LLM_ENDPOINT=http://localhost:8000
LLM_MODEL=mistral-7b-instruct

---

Verify Your Installation

jarviscore check

This command validates your Python version, package installation, and LLM configuration. To also test live inference against the configured provider:

jarviscore check --validate-llm

The exact Python version and configured provider vary. A successful check includes output like:

======================================================================
  JarvisCore Health Check
======================================================================

[System Requirements]
  Python Version:             3.12.2
    JarvisCore Package:         v1.13.0

[Dependencies]
  pydantic:                   Core validation
  pydantic_settings:          Configuration management

[LLM Configuration]
    Claude:                     CLAUDE_API_KEY=sk-a...key

[LLM Connectivity Test]
    Claude API:                 Connected

  All checks passed. Ready to use JarvisCore.

---

Choose Your Agent Profile

JarvisCore ships exactly two agent profiles. This is the first decision in every project:

	AutoAgent	CustomAgent
Who brings the logic	The framework: LLM reasoning, sandboxed code generation, self-repair	You: plain Python in execute_task
You write	role, capabilities, system_prompt	The implementation
Use for	Tasks you can describe: research, analysis, content, data extraction	Logic you can code: API workers, wrapping existing services, deterministic pipelines
Guide	AutoAgent guide	CustomAgent guide

Both run on the same mesh and mix freely in one system. Not sure? Start with AutoAgent below; switch any agent to CustomAgent later without touching the rest.

---

Your First Agent

Create a file named main.py:

main.py

import asyncio
from jarviscore import Mesh, AutoAgent


class ResearcherAgent(AutoAgent):
    role = "researcher"
    capabilities = ["research", "analysis"]
    description = "Researches topics and produces concise summaries."
    system_prompt = """
    You are a systematic research analyst. When given a topic,
    you identify the most relevant facts, verify them against
    multiple angles, and summarise your findings clearly.
    """


async def main():
    mesh = Mesh()
    mesh.add(ResearcherAgent)
    await mesh.start()
    try:
        result = await mesh.run_task(
            agent="researcher",
            task="What are the main architectural differences between the SWIM and Raft consensus protocols?",
        )
        print(result["output"])
    finally:
        await mesh.stop()


if __name__ == "__main__":
    asyncio.run(main())

Run it:

python main.py

The agent will reason through the task using the OODA loop and return a structured response. Because no infrastructure is configured beyond the LLM key, all state is held in process memory and discarded when the script exits.

The same identity contract applies to CustomAgent, but you own the execution logic:

main.py (CustomAgent variant)

from jarviscore.profiles import CustomAgent


class WordCountAgent(CustomAgent):
    role = "word_counter"
    capabilities = ["text_analysis"]

    async def execute_task(self, task):
        text = task["task"]
        return {
            "status": "success",
            "output": {"words": len(text.split())},
        }

Everything else on this page works identically for both profiles.

---

Your First Multi-Agent Workflow

The following example demonstrates a two-agent pipeline where a Scout gathers raw data and an Analyst processes it.

multi_agent.py

import asyncio
from jarviscore import Mesh, AutoAgent


class ScoutAgent(AutoAgent):
    role = "scout"
    capabilities = ["web_research"]
    description = "Gathers raw data on a given subject."
    system_prompt = "You gather raw, factual data on the subject provided. Be thorough and cite your sources."


class AnalystAgent(AutoAgent):
    role = "analyst"
    capabilities = ["analysis", "reporting"]
    description = "Analyses data and produces structured intelligence reports."
    system_prompt = "You receive raw research data and produce a structured intelligence report with clear conclusions."


async def main():
    mesh = Mesh()
    mesh.add(ScoutAgent)
    mesh.add(AnalystAgent)
    await mesh.start()
    try:
        results = await mesh.workflow("vector-database-report", [
            {
                "agent": "scout",
                "task": "Gather sourced evidence on the current state of vector database technology.",
            },
            {
                "agent": "analyst",
                "task": "Analyse the upstream evidence and produce a structured report.",
                "depends_on": [0],
            },
        ])
        print(results[-1]["output"])
    finally:
        await mesh.stop()


if __name__ == "__main__":
    asyncio.run(main())

---

Choose How Work Runs

API	Use it when	Planning owner	Redis required
mesh.run_task()	One known agent should handle one bounded task	Your application	No
agent.execute_goal()	One AutoAgent should plan and execute a multi-step goal internally	That AutoAgent	No
mesh.workflow()	Your application knows the agents, steps, and dependencies	Your application	No
mesh.execute_goal()	A source goal should become durable, capability-addressed work claimed by peers	Temporary planning lease	Yes

Rule of thumb: if your code manually passes one agent's output into another agent's prompt, use mesh.workflow(). If the steps are not known in advance and several peers should own the work, use mesh.execute_goal().

---

Next Steps

Once you have a working agent, add infrastructure incrementally based on your requirements.

Add persistent memory so agents retain context across runs:

docker run -d -p 6379:6379 redis:7-alpine

.env

REDIS_URL=redis://localhost:6379/0

Add cross-session semantic memory with Athena:

jarviscore memory init

Add third-party service credentials for agents that call external APIs:

jarviscore nexus init
jarviscore nexus register github --client-id=YOUR_ID --client-secret=YOUR_SECRET

Enable multi-node distributed execution with P2P:

.env

P2P_ENABLED=true
REDIS_URL=redis://localhost:6379/0
JARVISCORE_BIND_HOST=0.0.0.0
JARVISCORE_BIND_PORT=7946
# Set on nodes joining an existing seed node:
JARVISCORE_SEED_NODES=192.168.1.10:7946

Each process needs its own bind port. Redis is the shared work/state plane; SWIM and ZMQ provide cross-node discovery and communication.

Continue in this order:

1. Read Concepts for the runtime mental model.
2. Follow Guides to choose an agent profile and execution API.
3. Use Workflow DAGs when your application knows the steps.
4. Use Durable Goal Execution when peers should derive and claim work from a source goal.
5. Apply the Production Deployment checklist before running unattended workloads.

See the Configuration Reference for every environment variable and default.