Getting Started

Welcome to Astrsomn! This guide will help you deploy Astrsomn Server or integrate AI capabilities into your Spring Boot project.

---

Part 1: Server Deployment

From downloading the package to launching the service — deploy Astrsomn Server in minutes.

1. Prerequisites

Ensure the following are installed before deployment:

Environment	Version	Notes
JDK	17+	Runtime
MySQL	8.0+	Data storage
Node.js	18+	Frontend dev (source builds only)
Maven	3.8+	Project build (source builds only)

2. Download Package

Grab the platform-specific archive from GitHub Releases. Each package includes the embedded frontend, database migration scripts, and start/stop scripts.

📦 Download URL: https://github.com/Astrsomn/Astrsomn/releases

Platform	File
Windows	astrsomn-windows.zip
Linux	astrsomn-linux.tar.gz
macOS	astrsomn-macos.tar.gz

Directory structure after extraction:

astrsomn/
├── astrsomn-server.jar        # Spring Boot fat JAR (embedded frontend)
├── config/
│   └── application.yml         # Configuration
├── database/
│   └── V1__Initial.sql         # Schema migration
├── bin/
│   ├── start.sh / start.bat    # Start script
│   ├── stop.sh / stop.bat      # Stop script
│   └── .env                    # JVM options
└── VERSION                     # Version number

3. Create & Initialize Database

Log into MySQL and create the database. Flyway will auto-run V1__Initial.sql on first startup — no manual import needed.

-- Create the database
CREATE DATABASE astro_ai DEFAULT CHARACTER SET utf8mb4;

Manual import (optional)

If you prefer not to rely on Flyway auto-migration:

mysql -u root -p astro_ai < database/V1__Initial.sql

4. Edit Configuration

Open config/application.yml and set your MySQL credentials:

# config/application.yml
spring:
  profiles:
    active: mysql

astrsomn:
  enabled: true
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/astro_ai?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

server:
  port: 4481   # Default port

Security note

Change the default database password and JWT secret before deploying to production.

5. Start Server

Run the platform-specific start script. Tune JVM options via the .env file.

Windows

bin\start.bat

Linux / macOS

chmod +x bin/*.sh
./bin/start.sh

Key JVM options (bin/.env):

JAVA_OPTS=-Xms256m -Xmx1024m -Dfile.encoding=UTF-8

Parameter	Default	Description
-Xms	256m	Initial heap size
-Xmx	1024m	Max heap size
-Dfile.encoding	UTF-8	File encoding
Server port	4481	Configurable in application.yml

6. Access the Console

Once started, open http://localhost:4481 in your browser.

Item	Value
URL	http://localhost:4481
Default username	admin
Default password	admin

After first login

Change the default password immediately! Then go to the Console to complete initial setup:

1. Model Instances — Configure AI model connections (API Key, endpoint, etc.)
2. Agent Management — Create your first AI Agent
3. Account Management — Manage provider API accounts

---

Part 2: Framework Integration

Add Astrsomn as a Maven dependency to your Spring Boot project and invoke AI with a single annotation.

1. Add Maven Repository

Astrsomn is published on Sonatype Central. Add the Snapshots repository for SNAPSHOT versions:

<!-- pom.xml -->
<repositories>
  <repository>
    <id>central</id>
    <url>https://repo1.maven.org/maven2</url>
  </repository>
  <repository>
    <id>sonatype-snapshots</id>
    <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
</repositories>

2. Add Runtime Starter

astrsomn-runtime-starter is the core launcher — it auto-manages model, memory, and Spring container wiring:

<dependency>
  <groupId>com.astrsomn</groupId>
  <artifactId>astrsomn-runtime-starter</artifactId>
  <version>0.2.0-SNAPSHOT</version>
</dependency>

3. Choose a Model Provider

Pick at least one model provider. Multiple mainstream providers are available:

DeepSeek (Recommended)

<dependency>
  <groupId>com.astrsomn</groupId>
  <artifactId>astrsomn-provider-deepseek</artifactId>
  <version>0.2.0-SNAPSHOT</version>
</dependency>

Zhipu

<dependency>
  <groupId>com.astrsomn</groupId>
  <artifactId>astrsomn-provider-zhipu</artifactId>
  <version>0.2.0-SNAPSHOT</version>
</dependency>

OpenAI

<dependency>
  <groupId>com.astrsomn</groupId>
  <artifactId>astrsomn-provider-openai</artifactId>
  <version>0.2.0-SNAPSHOT</version>
</dependency>

4. Configure Datasource

Ensure your project has Spring Boot + MyBatis-Plus + MySQL driver, then configure the database:

# application.yml
spring:
  profiles:
    active: mysql

# application-mysql.yml
astrsomn:
  enabled: true
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/astro_ai?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: root

5. Use @Astro to Inject

Add @EnableAstroRuntime to your Spring Boot application class, then use @Astro to inject assistants:

// 1. Enable the framework
@EnableAstroRuntime
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

// 2. Inject via @Astro in your Service
@Service
public class MyService {

    @Astro(agentKey = "MY-AGENT", envCode = "PRO")
    private AstroChatAssistant assistant;

    public void demo() {
        String reply = assistant.chat("Hello, Astrsomn!", "session-001");
        System.out.println(reply);
    }
}

@Astro Parameters

Parameter	Type	Description
agentKey	String	Unique Agent identifier (pre-created in console)
envCode	String	Environment code for multi-env isolation
promptKey	String	Associated Prompt template key (optional)
enableStream	boolean	Enable streaming output (optional)
enableNetwork	boolean	Enable web search (optional)
enableDeepThinking	boolean	Enable deep thinking mode (optional)

---

Next Steps

• Framework Usage — Deep dive into model config, MCP, tools, prompts
• Framework Development — Learn to build custom providers, vector stores, MCP
• Project Architecture — Understand the architecture and module design