Configuration Reference#

Everything you can configure in Adama -- CLI settings, document behavior, services, privacy, cron schedules, deployment. Some of this you'll set once and forget; some of it you'll reference every time you start a new project.

CLI Configuration File#

The Adama CLI stores its configuration in ~/.adama by default. This file gets created when you run adama init.

File Location#

Override with:

adama --config /path/to/config <command>

Configuration Structure#

{
  "identity": "<jwt-token>",
  "email": "developer@example.com",
  "default-space": "my-project"
}

Fields#

Document Configuration (@static)#

The @static block in your Adama code configures document-level behavior. This is where you set creation policies and document settings.

Syntax#

@static {
  // Creation policies
  create { return true; }
  invent { return true; }

  // Document settings
  maximum_history = 100;
  delete_on_close = false;
}

Creation Policies#

create#

Controls who can explicitly create documents in this space.

@static {
  create {
    // Return true to allow, false to deny
    return @who != @no_one;  // Require authentication
  }
}

Available Context:

• @who - Principal attempting creation
• @context - Request context (origin, IP)

Examples:

// Allow anyone
@static {
  create { return true; }
}

// Require authentication
@static {
  create { return @who != @no_one; }
}

// Check origin
@static {
  create {
    return @context.origin == "https://myapp.com";
  }
}

// Allow only Adama developers
@static {
  create {
    return @who.isAdamaDeveloper();
  }
}

invent#

Controls whether documents can be created on-demand when a user connects to a non-existent document key. This is one of those features that sounds weird until you need it, and then it's exactly what you want.

@static {
  invent {
    return true;  // Allow document invention
  }
}

When you'd use this:

• Per-user documents created automatically (connect to "user-alice", and if it doesn't exist, it gets created)
• Dynamic document creation without explicit API calls
• Ephemeral documents

Examples:

// Allow invention for authenticated users
@static {
  invent {
    return @who != @no_one;
  }
}

// Allow invention for anyone
@static {
  invent { return true; }
}

// Disable invention
@static {
  invent { return false; }
}

Document Settings#

maximum_history#

Maximum number of history entries to retain. Used for undo/redo and audit trails.

@static {
  maximum_history = 100;  // Keep last 100 changes
}

Default: Platform-dependent (typically 100)

delete_on_close#

Whether to automatically delete the document when all connections close. For ephemeral sessions where you don't want data hanging around.

@static {
  delete_on_close = true;  // Delete when empty
}

Default: false

When you'd use this:

• Ephemeral game sessions
• Temporary collaboration rooms
• Stateless interactions

Complete @static Example#

@static {
  // Only authenticated users from specific origin can create
  create {
    return @who != @no_one &&
           (@context.origin == "https://myapp.com" ||
            @context.origin == "https://staging.myapp.com");
  }

  // Allow document invention for any authenticated user
  invent {
    return @who != @no_one;
  }

  // Keep 200 history entries
  maximum_history = 200;

  // Don't auto-delete
  delete_on_close = false;
}

Space Configuration#

Space configuration is managed through the CLI and platform API.

Space Settings#

Service Configuration#

External services are configured within service blocks in your Adama code.

Service Block Syntax#

message RequestType {
  string data;
}

message ResponseType {
  string result;
}

service ServiceName {
  class = "service.class.name";
  method<RequestType, ResponseType> methodName;
}

Common Service Classes#

Service Configuration Example#

service Email {
  class = "email";
  method<SendRequest, SendResponse> send;
}

message SendRequest {
  string to;
  string subject;
  string body;
}

message SendResponse {
  bool success;
  string messageId;
}

Environment Variables#

The CLI and runtime respect these environment variables:

Setting Environment Variables#

Linux/macOS:

export ADAMA_CONFIG=/path/to/config
export ADAMA_TOKEN="your-token"

Windows (Command Prompt):

set ADAMA_CONFIG=C:\path\to\config
set ADAMA_TOKEN=your-token

Windows (PowerShell):

$env:ADAMA_CONFIG = "C:\path\to\config"
$env:ADAMA_TOKEN = "your-token"

Web Handler Configuration#

Web handlers are configured through response objects.

Response Configuration#

@web get /api/data {
  return {
    json: { data: "value" },
    cors: true,
    cache_ttl_seconds: 3600
  };
}

Response Options#

CORS Configuration#

When cors: true is set, these headers are added:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Cron Configuration#

Scheduled tasks use the @cron annotation.

Schedule Types#

Dynamic Schedules#

You can use document fields for runtime-configurable schedules, which is nice when you want users or admins to control when things run:

private time daily_time;
private int hourly_minute;
private int monthly_day;

@cron daily_task daily daily_time { }
@cron hourly_task hourly hourly_minute { }
@cron monthly_task monthly monthly_day { }

Privacy Configuration#

Privacy is configured through modifiers and policies.

Privacy Modifiers#

Policy Configuration#

policy policy_name {
  // Return true to show, false to hide
  return true;
}

use_policy<policy_name> int sensitive_data;

Multiple Policies#

Combine policies with commas (logical AND -- all must return true):

policy is_authenticated { return true; }
policy is_not_banned { return true; }
policy has_permission { return true; }

use_policy<is_authenticated, is_not_banned, has_permission> int protected_data;

Index Configuration#

Table indexes speed up queries.

Index Syntax#

record Player {
  public int id;
  public string name;
  public int score;

  index name;
  index score;
}

Index Types#

Deployment Configuration#

Space Deployment#

adama space deploy --name <space> --file <file.a> [options]

Deployment Best Practices#

1. Validate first:

   adama code validate --file main.a
   

2. Run tests:

   adama code test --file main.a
   

3. Deploy to staging:

   adama space deploy --name staging --file main.a
   

4. Verify staging: Test the staging environment before production.

5. Deploy to production:

   adama space deploy --name production --file main.a
   

Configuration At a Glance#