Quick start

The Faimulus sample app shows how a complete application is assembled from an Angular frontend, a Spring Boot gateway, and a versioned Faimulus workspace. The workspace defines the models, memories, toolsets, trusted drivers, and workflows that provide the application's behavior.

Prerequisites

Install:

• Git
• Docker
• Docker Compose

Docker Desktop is the recommended option for Windows, macOS, and Linux because it includes Docker Compose. Linux users can instead install Docker Engine and the Docker Compose plugin separately.

Verify that they are available:

git --version
docker --version
docker compose version

Configure the sample app

Clone the repository and create your local environment file:

git clone https://github.com/faimulus/faimulus-sample-app.git
cd faimulus-sample-app
cp .env.example .env

Review .env before starting the stack:

• Set ADMIN_PASSWORD to enable the local admin login, or leave it blank to run without authentication.
• Keep FAIMULUS_API_KEY equal to the Faimulus server's APPLICATION_API_KEY.
• Replace the example secrets before running the stack outside local development.

Choose an AI provider

Use an account or endpoint you already have. The sample supports:

• OpenRouter: set OPENROUTER_API_KEY in .env. The openrouter provider is enabled and selected by default. Use an OpenRouter model ID, such as the default openai/gpt-4.1.
• OpenAI: create or copy a key from OpenAI API keys, then set OPENAI_API_KEY in .env. This driver uses the native OpenAI Responses API.
• Anthropic: create or copy a key from the Anthropic Console, then set ANTHROPIC_API_KEY in .env. This driver uses the native Messages API and defaults maxTokens to 4096.
• Google: create or copy a key from Google AI Studio, then set GOOGLE_API_KEY in .env. This driver uses the Gemini Developer API; Vertex AI credentials are not supported.
• OpenAI-compatible: set OPENAI_COMPATIBLE_API_KEY in .env when the endpoint requires authentication. The key is optional for unauthenticated endpoints. This driver uses the Chat Completions API and can connect to a local or remote endpoint.

If you do not have a provider account, create an OpenRouter account, add credits, and create an API key. USD 5 is sufficient for evaluating and developing the sample.

Select the provider and model

OpenRouter needs no YAML changes because it is already enabled and selected. For OpenAI, Anthropic, Google, or an OpenAI-compatible endpoint:

1. Open workspace/config/providers.yaml and uncomment the provider block you want to use: openai, anthropic, google, or local.
2. For an OpenAI-compatible provider, set baseUrl in the local block to the endpoint's /v1 URL. The local name is only an example and may be changed.
3. Open workspace/config/models.yaml and set models.general.provider to the provider instance name from providers.yaml.
4. Set models.general.config.model to a model ID supported by that provider or endpoint.

For example, selecting the enabled anthropic provider looks like this:

version: 1
models:
	general:
		provider: anthropic
		config:
			model: <anthropic-model-id>

Keep API keys private, do not commit .env, and restart the Faimulus container after changing provider or model configuration.

Start the stack

Start the application:

docker compose up --build

Wait for the services to become ready, then open http://localhost:8080. The Faimulus API is available at http://localhost:3000.

Run a workflow

1. Open Workflows and choose a webhook from the Call and debug webhooks page.
2. Enter the workflow input. To control execution one node at a time, select Debug (run one node at a time).
3. Select Start workflow. A debug run opens the Graph tab and pauses before each subsequent node.
4. Follow the status shown on each graph node. When the run is paused, select Next step to execute the next node.
5. Select a graph node to inspect its configuration and Run state, including its latest output, in the details panel.

Open the Inspector to see the models, memories, and toolsets currently available to the application. These resources and the workflows that use them are defined under workspace/ in the cloned repository.

To stop the application, press Ctrl+C in the terminal running Docker Compose.

For alternative provider setup, local development commands, service endpoints, and driver development, see the sample app README.