Remote Config

Feature flags and dynamic configuration with segment-based conditions and percentage rollouts.

Remote config lets you change app behavior without shipping an update. Set key / value pairs on the server, attach optional per-segment or percentage-rollout conditions, and the SDK fetches them with built-in TTL caching and ETag support.

How it works

Admins (or AI agents via MCP) set config values on the server. Every value has a type (string, number, boolean, json) and optional conditions that override the default for specific segments or a percentage of users.
The client SDK fetches the resolved map from GET /client/config, caches it in your storage, and refreshes on a TTL or on refresh() call.
ETags + If-None-Match keep refreshes cheap — a 304 response tells the SDK to reuse the cached payload and just bump the timestamp.
Server-side version hashes make change detection fast: flipping a value bumps config_versions.version_hash, invalidating every client cache.

SDK usage

Method signatures:

client.config.get(key: string): Promise<unknown>
client.config.getAll(): Promise<Record<string, unknown>>
client.config.refresh(): Promise<void>
client.config.restore(): Promise<void>  // called automatically by init()

Get a single value

const dailyLimit = (await client.config.get('daily_limit')) as number | undefined;
// undefined if the key isn't set

Because the value is typed as unknown, cast to your expected type. Always provide a default:

const limit = ((await client.config.get('daily_limit')) as number | undefined) ?? 10;

Get the full config map

const all = await client.config.getAll();
// { daily_limit: 10, feature_paywall_v2: true, ... }

Force refresh

await client.config.refresh();
// Bypasses the TTL, hits the server, updates cache + ETag

Expo

import { Amba } from '@amba/expo';
 
function SettingsScreen() {
  const [limit, setLimit] = useState<number | null>(null);
  const [paywall, setPaywall] = useState(false);
 
  useEffect(() => {
    (async () => {
      setLimit(((await Amba.configModule.get('daily_limit')) as number | undefined) ?? 10);
      setPaywall((await Amba.configModule.get('feature_paywall_v2')) === true);
    })();
  }, []);
 
  return (
    <View>
      <Text>Daily limit: {limit}</Text>
      {paywall && <PaywallBanner />}
    </View>
  );
}

The Expo wrapper exposes the module as configModule (not config) because config collides with common React prop / state naming. Note: Amba.init() already calls restore() and a background refresh() for you — your first read is served from the cache.

Manual refresh in Expo

await Amba.configModule.refresh();

Conditional values

A single config key can return different values to different users. Conditions are evaluated on the server and resolved into a single payload the SDK sees as flat key → value.

Example schema stored in remote_configs.conditions:

{
  "key": "feature_paywall_v2",
  "value_type": "boolean",
  "default_value": false,
  "conditions": [
    { "segment_id": "seg_power_users", "value": true },
    { "percentage": 25, "value": true }
  ]
}

This sets the default to false, enables it for all members of seg_power_users, and rolls it out to 25% of everyone else.

Setting config values

Via the Admin API

POST /admin/projects/:projectId/config
Authorization: Bearer <developer token>
 
{
  "key": "daily_limit",
  "value": 10,
  "value_type": "number",
  "description": "Maximum daily actions allowed"
}

Via MCP

Agent: Enable the new onboarding flow for 10% of users.

amba_set_config({
  project_id: "proj_xxx",
  key: "feature_onboarding_v2",
  value: false,
  value_type: "boolean",
  description: "New onboarding experience",
  conditions: [{ percentage: 10, value: true }]
})

Via the CLI

amba config set daily_limit 10
amba config set feature_paywall_v2 true
amba config list

Routes reference

Method	Path	Description
`GET`	`/client/config`	Fetch resolved config. Supports `If-None-Match` → 304.
`POST`	`/admin/projects/:projectId/config`	Create or update a config value
`GET`	`/admin/projects/:projectId/config`	List all active config values
`PATCH`	`/admin/projects/:projectId/config/:key`	Update a specific config
`DELETE`	`/admin/projects/:projectId/config/:key`	Delete a config value

MCP tools

Tool	Description
`amba_get_config`	Read a specific key for a project
`amba_set_config`	Create / update a key with optional conditions

Database tables

Table	Purpose
`remote_configs`	Key / value / type / conditions / default_value per key
`config_versions`	Single-row `version_hash` that bumps on every change. Used for ETag.

On this page